Merge branch 'develop'

Implements PDCA feature

.dockerignore

@@ -10,7 +10,14 @@ node_modules/
 client/
 dist/
 build/
+coverage/
+tests/
+vitest.config.js
+.markdownlint.json
 README.md
+CHANGELOG.md
+SECURITY.md
+LICENSE
 .dockerignore
 Dockerfile
 .gitea/

.env.example

@@ -1,37 +0,0 @@
-# Server Configuration
-PORT=3001
-LOG_LEVEL=info
-
-# Cookie signing secret for tamper-proof session cookies
-# Required in production. Generate with: openssl rand -hex 32
-COOKIE_SECRET=your_cookie_secret_here
-
-# Set to 1 (or a specific IP/CIDR) when running behind a reverse proxy
-# (Nginx, Caddy, Traefik) so Express trusts X-Forwarded-For/Proto.
-# Leave unset if sofarr is exposed directly.
-# TRUST_PROXY=1
-
-# Directory for persistent data (SQLite token store + logs)
-# Defaults to ./data relative to project root
-# DATA_DIR=/app/data
-
-# Background polling interval in ms (default: 5000)
-# Set to 0 or "off" to disable and fetch on-demand instead
-# POLL_INTERVAL=5000
-
-# Emby Configuration (single instance)
-EMBY_URL=http://localhost:8096
-EMBY_API_KEY=your_emby_api_key
-
-# SABnzbd Instances (JSON array)
-# Format: [{"name": "Instance Name", "url": "http://...", "apiKey": "..."}]
-SABNZBD_INSTANCES=[{"name": "Primary", "url": "http://localhost:8080", "apiKey": "your_api_key"}]
-
-# Sonarr Instances (JSON array)
-SONARR_INSTANCES=[{"name": "Primary", "url": "http://localhost:8989", "apiKey": "your_api_key"}]
-
-# Radarr Instances (JSON array)
-RADARR_INSTANCES=[{"name": "Primary", "url": "http://localhost:7878", "apiKey": "your_api_key"}]
-
-# qBittorrent Instances (JSON array)
-QBITTORRENT_INSTANCES=[{"name": "main", "url": "http://localhost:8080", "username": "admin", "password": "your_password"}]

.env.sample

@@ -19,6 +19,24 @@ LOG_LEVEL=info
 # Generate with: openssl rand -hex 32
 COOKIE_SECRET=your-cookie-secret-here
 
+# =============================================================================
+# TLS / HTTPS
+# =============================================================================
+
+# TLS is enabled by default using the bundled snakeoil self-signed certificate
+# (valid for localhost/127.0.0.1, 10-year expiry).
+# Set TLS_CERT and TLS_KEY to use your own certificate (recommended).
+# Set TLS_ENABLED=false to run in plain HTTP mode (e.g. behind a TLS proxy).
+#
+# To generate a self-signed cert for your own hostname:
+#   openssl req -x509 -newkey rsa:2048 -keyout server.key -out server.crt \
+#     -days 365 -nodes -subj "/CN=yourhostname" \
+#     -addext "subjectAltName=DNS:yourhostname,IP:192.168.x.x"
+#
+# TLS_ENABLED=true
+# TLS_CERT=/path/to/server.crt
+# TLS_KEY=/path/to/server.key
+
 # =============================================================================
 # REVERSE PROXY & DEPLOYMENT
 # =============================================================================
@@ -34,6 +52,10 @@ COOKIE_SECRET=your-cookie-secret-here
 # Defaults to ./data relative to the project root.
 # DATA_DIR=/app/data
 
+# Number of days of completed download history to show in the Recently Completed section.
+# Override per-request with ?days=N (capped at 90).
+# RECENT_COMPLETED_DAYS=7
+
 # Background polling interval in milliseconds (default: 5000)
 # sofarr polls all services in the background and caches results so
 # dashboard requests are near-instant.
@@ -72,6 +94,17 @@ QBITTORRENT_INSTANCES=[{"name":"main","url":"https://qbittorrent.example.com","u
 # QBITTORRENT_USERNAME=admin
 # QBITTORRENT_PASSWORD=your-password
 
+# =============================================================================
+# RTORRENT_INSTANCES (JSON Array)
+# The url MUST include the full XML-RPC endpoint path.
+# Standard/self-hosted installs: .../RPC2
+# whatbox.ca users: .../xmlrpc
+# Other installations may use different custom paths.
+# Example:
+RTORRENT_INSTANCES=[{"name":"main","url":"http://rtorrent.local:8080/RPC2","username":"rtorrent","password":"rtorrent"}]
+# For whatbox.ca:
+# RTORRENT_INSTANCES=[{"name":"whatbox","url":"https://user.whatbox.ca/xmlrpc","username":"user","password":"pass"}]
+
 # =============================================================================
 # SONARR INSTANCES (JSON Array Format)
 # Add one or more Sonarr instances as a single-line JSON array

.gitea/workflows/build-image.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - 'release/**'
-      - 'develop'
+      - 'develop*'
 
 jobs:
   build:
@@ -20,9 +20,11 @@ jobs:
           BRANCH=${GITHUB_REF#refs/heads/}
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
 
-          if [ "$BRANCH" = "develop" ]; then
-            echo "tags=reg.i3omb.com/sofarr:develop" >> $GITHUB_OUTPUT
-            echo "Building develop image (version ${VERSION})"
+          if [[ "$BRANCH" == develop* ]]; then
+            # Sanitise branch name for tag: replace slashes with dashes
+            SAFE_BRANCH=$(echo "$BRANCH" | tr '/' '-')
+            echo "tags=reg.i3omb.com/sofarr:${SAFE_BRANCH}" >> $GITHUB_OUTPUT
+            echo "Building develop image ${SAFE_BRANCH} (version ${VERSION})"
           else
             RELEASE_NAME=${BRANCH#release/}
             TAGS="reg.i3omb.com/sofarr:${VERSION}"

.gitea/workflows/docs-check.yml

@@ -0,0 +1,108 @@
+name: Docs Check
+
+on:
+  push:
+    branches: ["**", "!main", "!release/**"]
+    paths:
+      - "**.md"
+      - ".gitea/workflows/docs-check.yml"
+  pull_request:
+    branches: ["**", "!main", "!release/**"]
+    paths:
+      - "**.md"
+      - ".gitea/workflows/docs-check.yml"
+
+jobs:
+  markdown-lint:
+    name: Markdown lint
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install markdownlint-cli
+        run: npm install -g markdownlint-cli
+
+      - name: Lint all Markdown files
+        run: markdownlint "**/*.md" --ignore node_modules
+
+  mermaid-parse:
+    name: Mermaid diagram parse check
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install mermaid and jsdom
+        run: npm install mermaid jsdom
+
+      - name: Extract and validate Mermaid diagrams
+        run: |
+          cat > check-mermaid.cjs << 'SCRIPT'
+          const { JSDOM } = require('jsdom');
+          const fs   = require('fs');
+          const path = require('path');
+
+          // Provide minimal browser globals so mermaid.parse() works in Node
+          const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', { url: 'http://localhost' });
+          globalThis.window   = dom.window;
+          globalThis.document = dom.window.document;
+          globalThis.DOMPurify = {
+            addHook: () => {}, removeHook: () => {}, setConfig: () => {},
+            sanitize: (s) => s, isValidAttribute: () => true,
+          };
+
+          function findMdFiles(dir) {
+            const out = [];
+            for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+              const full = path.join(dir, e.name);
+              if (e.isDirectory() && e.name !== 'node_modules' && !e.name.startsWith('.'))
+                out.push(...findMdFiles(full));
+              else if (e.isFile() && e.name.endsWith('.md'))
+                out.push(full);
+            }
+            return out;
+          }
+
+          import('./node_modules/mermaid/dist/mermaid.core.mjs').then(async (m) => {
+            const mermaid = m.default;
+            let errors = 0, total = 0;
+
+            for (const mdFile of findMdFiles('.')) {
+              const content = fs.readFileSync(mdFile, 'utf8');
+              const blocks = [...content.matchAll(/^```mermaid\n([\s\S]*?)^```/gm)];
+              if (!blocks.length) continue;
+              console.log(`\nChecking ${mdFile} (${blocks.length} diagram(s))`);
+              for (let i = 0; i < blocks.length; i++) {
+                total++;
+                const diagram = blocks[i][1].trim();
+                try {
+                  await mermaid.parse(diagram);
+                  console.log(`  [OK]  diagram ${i + 1}`);
+                } catch (err) {
+                  const msg = String(err.message || err).split('\n')[0];
+                  console.error(`  [FAIL] diagram ${i + 1}: ${msg}`);
+                  console.log(`::warning file=${mdFile}::Mermaid diagram ${i + 1} failed: ${msg}`);
+                  errors++;
+                }
+              }
+            }
+
+            console.log(`\nTotal: ${total}. Failures: ${errors}`);
+            if (errors > 0) {
+              console.log(`::warning::${errors} Mermaid diagram(s) failed to parse.`);
+              process.exit(1);
+            }
+          }).catch(e => { console.error('Fatal:', e.message); process.exit(1); });
+          SCRIPT
+          node check-mermaid.cjs

.gitea/workflows/licence-check.yml

@@ -0,0 +1,83 @@
+name: Licence Check
+
+on:
+  push:
+    branches: ["**", "!main", "!release/**"]
+    paths:
+      - "package.json"
+      - "package-lock.json"
+      - ".gitea/workflows/licence-check.yml"
+      - "**/*.js"
+      - "**/*.ts"
+      - "**/*.jsx"
+      - "**/*.tsx"
+  pull_request:
+    branches: ["**", "!main", "!release/**"]
+    paths:
+      - "package.json"
+      - "package-lock.json"
+      - ".gitea/workflows/licence-check.yml"
+      - "**/*.js"
+      - "**/*.ts"
+      - "**/*.jsx"
+      - "**/*.tsx"
+
+jobs:
+  licence-check:
+    name: Licence compatibility and copyright header verification
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install production dependencies
+        run: npm ci --omit=dev
+
+      - name: Check licence compatibility
+        run: |
+          npx --yes license-checker --production \
+            --onlyAllow "MIT;ISC;MIT-0;BSD-2-Clause;BSD-3-Clause;Apache-2.0;CC0-1.0;BlueOak-1.0.0" \
+            --excludePrivatePackages \
+            && echo "All production dependency licences are compatible with MIT."
+
+      - name: Check copyright headers in source files
+        run: |
+          #!/bin/bash
+          set -e
+          
+          # Find all source files, excluding build artifacts and node_modules
+          SOURCE_FILES=$(find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \) \
+            ! -path "./node_modules/*" \
+            ! -path "./.git/*" \
+            ! -path "./dist/*" \
+            ! -path "./build/*" \
+            ! -path "./.gitea/*")
+          
+          MISSING_HEADER=0
+          
+          # Check each file for MIT-compliant copyright header
+          while IFS= read -r file; do
+            if [ -z "$file" ]; then
+              continue
+            fi
+            
+            # Check if file starts with a copyright header containing: Copyright, year (4 digits), name, and MIT License
+            if ! head -n 5 "$file" | grep -qiE "Copyright.*[0-9]{4}.*MIT"; then
+              echo "❌ Missing MIT-compliant copyright header in: $file"
+              echo "   Required format: // Copyright (c) YYYY Name. MIT License."
+              MISSING_HEADER=$((MISSING_HEADER + 1))
+            fi
+          done <<< "$SOURCE_FILES"
+          
+          if [ $MISSING_HEADER -gt 0 ]; then
+            echo ""
+            echo "⚠️  Found $MISSING_HEADER file(s) with missing or non-compliant copyright headers."
+            exit 1
+          else
+            echo "✅ All source files have MIT-compliant copyright headers."
+          fi

.markdownlint.json

@@ -0,0 +1,18 @@
+{
+  "default": true,
+  "MD009": false,
+  "MD012": false,
+  "MD013": false,
+  "MD022": false,
+  "MD024": false,
+  "MD029": false,
+  "MD031": false,
+  "MD032": false,
+  "MD033": false,
+  "MD034": false,
+  "MD036": false,
+  "MD040": false,
+  "MD041": false,
+  "MD058": false,
+  "MD060": false
+}

CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.3.0] - 2026-05-17
+
+### Added
+
+- **History tab** — new "Recently Completed" tab showing imported and failed downloads from Sonarr/Radarr history for the last N days (configurable via the days input, persisted in `localStorage`). Auto-refreshes every 5 minutes.
+- **History deduplication** — when a failed download has subsequently been imported successfully, only the successful record is shown. If the most recent record for an item is a failure but the episode/movie is already on disk (upgrade attempt), the record is flagged as `availableForUpgrade`.
+- **"Upgrade available" badge** — failed history cards where the content is already on disk display an amber badge to indicate this is a failed upgrade rather than a missing item.
+- **"Hide upgrade failures" toggle** — checkbox in the history tab to filter out failed records that are already available on disk. State persists in `localStorage`. Tooltip explains the behaviour and matches the episode/multi-episode tooltip style.
+- **Blocklist & Search button** — admin-only button on download cards with an "Import Pending" caution. Removes the download from the client with `blocklist=true` (preventing re-grab of the same release) then immediately triggers an `EpisodeSearch`/`MoviesSearch` command in Sonarr/Radarr. Shows a confirmation dialog, loading/success/error states. Kicks a background poll on success.
+- **`POST /api/dashboard/blocklist-search`** — new admin-only endpoint backing the above button. Accepts `arrQueueId`, `arrType`, `arrInstanceUrl`, `arrInstanceKey`, `arrContentId`, `arrContentType`.
+- **Title link home navigation** — the sofarr logo/title in the header now navigates to the default view (Active Downloads tab, close status panel, reset "Show all users" toggle) without a page reload.
+- **Version footer link** — the version string in the dashboard footer links to the source repository.
+
+### Changed
+
+- History records are now deduplicated server-side before being sent to the client — only the most relevant record per content item per instance is returned.
+- Import-issue badge tooltip now uses the themed `var(--surface)` / `var(--text-primary)` / `var(--border)` CSS variables, matching the episode and toggle tooltip style.
+- Poller now stores `_instanceKey` on Sonarr/Radarr queue records in the cache, enabling the backend to look up API credentials for blocklist operations without an additional configuration lookup.
+- **Blocklist & Search button** — now available on all admin downloads (not just those with import issues), and also available to non-admin users when: import issues are present, OR (for qBittorrent torrents only) the download is more than 1 hour old AND has less than 100% availability.
+- **Download object** — added `canBlocklist` boolean field to indicate whether the current user can blocklist a given download.
+- **qBittorrent torrent data** — added `addedOn` timestamp field to enable age-based blocklist eligibility checks.
+
+---
+
+## [1.2.2] - 2026-05-17
+
+### Changed
+
+- **Header logo** — uses the higher-resolution 192px favicon source rendered at 56px for better visual balance alongside the title text.
+
+---
+
+## [1.2.1] - 2026-05-17
+
+### Added
+
+- **Version footer** — the dashboard footer now displays the running app version (e.g. `sofarr v1.2.1`), fetched from the `/health` endpoint on page load.
+
+---
+
+## [1.2.0] - 2025-05-17
+
+### Security
+
+- **Docker secrets support** — all sensitive environment variables (`COOKIE_SECRET`, `EMBY_API_KEY`, `SABNZBD_API_KEY`, `SONARR_API_KEY`, `RADARR_API_KEY`, `QBITTORRENT_PASSWORD`) now support the standard `_FILE` variant for loading values from mounted secret files (e.g. `COOKIE_SECRET_FILE=/run/secrets/cookie_secret`).
+- **Weak secret warning** — server now warns at startup if `COOKIE_SECRET` is shorter than 32 characters.
+- **EMBY_URL validation** — validates the Emby URL scheme at startup and warns on misconfiguration.
+- **Improved error sanitization** — `sanitizeError()` now also redacts hostnames from full request URLs that may appear in axios error messages.
+- **Graceful shutdown** — `SIGTERM` and `SIGINT` handlers now stop the background poller and drain open HTTP connections before exiting. Prevents data loss and zombie processes on `docker stop`.
+
+### Compliance
+
+- **MIT LICENSE file** added to project root.
+- **Copyright headers** added to key server source files (`index.js`, `poller.js`, `config.js`, `sanitizeError.js`, `loadSecrets.js`).
+- **`security.txt`** (`/.well-known/security.txt`) added for responsible disclosure.
+
+### Configuration
+
+- **URL validation** added to `config.js` — all configured service instance URLs are validated for scheme (`http`/`https`) and well-formedness at startup; malformed URLs emit a warning instead of crashing.
+
+### Docker / Deployment
+
+- **`docker-compose.yaml`** updated with commented Option B (Docker secrets `_FILE` pattern) alongside the existing plain-env Option A.
+- **`.dockerignore`** updated — `tests/`, `coverage/`, `vitest.config.js`, `CHANGELOG.md`, `SECURITY.md`, `LICENSE`, `.markdownlint.json` excluded from the production image.
+
+### CI
+
+- **`docs-check` workflow** added — separate Gitea Actions workflow that lints all Markdown files and validates Mermaid diagram syntax on every push that touches `.md` files. Both jobs use `continue-on-error: true` so documentation issues never block a release.
+- **Mermaid diagrams** in `docs/ARCHITECTURE.md` fixed — replaced invalid `\n` in stateDiagram transition labels, Unicode arrows/dashes, and double-spaces in flowchart edge definitions.
+
+---
+
+## [1.1.2] - 2025-05-15
+
+### Changed
+
+- Server startup message now includes the current version (`sofarr v1.1.2`).
+
+---
+
+## [1.1.1] - 2025-05-14
+
+### Fixed
+
+- Docker/TrueNAS SCALE healthcheck: dynamic HTTP/HTTPS selection based on `TLS_ENABLED` environment variable. Prevents containers from being stuck in "starting" state when `TLS_ENABLED=false`.
+
+---
+
+## [1.1.0] - 2025-05-13
+
+### Added
+
+- **Episode display** — TV show download cards now show episode information (S01E01 format with title). Multi-episode packs show a "Multiple episodes" badge with a tooltip listing all episodes.
+- **Episode tooltip** — solid background colour (theme-dependent) for readability.
+- Sonarr queue and history API requests now include `includeEpisode=true`.
+
+---
+
+## [1.0.0] - 2025-05-01
+
+### Added
+
+- Initial release.
+- SABnzbd queue and history integration.
+- qBittorrent torrent integration.
+- Sonarr and Radarr queue/history matching with user tag filtering.
+- Emby/Jellyfin authentication.
+- Server-Sent Events (SSE) real-time dashboard.
+- Per-request CSP nonce, CSRF double-submit, HSTS, Permissions-Policy.
+- Background polling with configurable interval and on-demand fallback.
+- Docker multi-stage build, non-root user, read-only filesystem.
+- TLS support with bundled snakeoil certificate.

Dockerfile

@@ -34,6 +34,9 @@ COPY --from=deps /app/node_modules ./node_modules
 COPY --chown=root:root server/ ./server/
 COPY --chown=root:root public/ ./public/
 COPY --chown=root:root package.json ./
+# Bundled snakeoil certificate for out-of-the-box TLS (self-signed, localhost only).
+# Mount your own cert/key over /app/certs/ or set TLS_CERT/TLS_KEY env vars.
+COPY --chown=root:root certs/ ./certs/
 
 # Persistent data directory owned by node user (token store, logs)
 RUN mkdir -p /app/data && chown node:node /app/data
@@ -46,8 +49,10 @@ USER node
 
 EXPOSE 3001
 
-# HEALTHCHECK — Docker will restart the container if this fails 3 times
+# HEALTHCHECK — Docker will restart the container if this fails 3 times.
+# Respects TLS_ENABLED at runtime: uses https (with --no-check-certificate
+# to handle self-signed/snakeoil certs) when TLS is on, plain http when off.
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-  CMD wget -qO- http://localhost:3001/health || exit 1
+  CMD /bin/sh -c '[ "${TLS_ENABLED:-true}" = "false" ] && wget -qO- http://localhost:${PORT:-3001}/health || wget -qO- --no-check-certificate https://localhost:${PORT:-3001}/health'
 
 CMD ["node", "server/index.js"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gordon Bolton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -7,8 +7,9 @@
 ## What It Does
 
 sofarr connects to your media stack and shows you a personalized view of:
-- **Active Downloads** - See what's currently downloading from Usenet (SABnzbd) and BitTorrent (qBittorrent)
+- **Active Downloads** - See what's currently downloading from Usenet (SABnzbd) and BitTorrent (qBittorrent, Transmission, rTorrent)
 - **Progress Tracking** - Real-time progress bars with speed, ETA, and completion estimates
+- **Recently Completed** - History tab showing imported and failed downloads from Sonarr/Radarr with deduplication and upgrade-awareness
 - **User Matching** - Downloads are matched to you based on tags in Sonarr/Radarr
 - **Multi-Instance Support** - Connect to multiple instances of each service
 
@@ -20,7 +21,9 @@ sofarr connects to your media stack and shows you a personalized view of:
 ┌─────────────┐     ┌──────────────┐     ┌─────────────────────────────┐
 │   Browser   │────▶│   sofarr     │────▶│  SABnzbd (Usenet downloads)   │
 │   (User)    │◀────│   Server     │     │  qBittorrent (Torrents)       │
-└─────────────┘     └──────────────┘     │  Sonarr (TV management)       │
+└─────────────┘     └──────────────┘     │  Transmission (Torrents)      │
+                       │                 │  rTorrent (Torrents)          │
+                       │                 │  Sonarr (TV management)       │
                        │                 │  Radarr (Movie management)    │
                        │                 │  Emby (User authentication)   │
                        ▼                 └─────────────────────────────┘
@@ -33,10 +36,10 @@ sofarr connects to your media stack and shows you a personalized view of:
 ### The Matching Process
 
 1. **User Authentication**: Login via Emby credentials
-2. **Tag-Based Matching**: 
+2. **Tag-Based Matching**:
    - Your media in Sonarr/Radarr is tagged with your username (e.g., "gordon")
    - sofarr checks Sonarr/Radarr activity to find items tagged with your name
-   - Downloads (from SABnzbd/qBittorrent) are matched by title to that activity
+   - Downloads (from SABnzbd, qBittorrent, Transmission, or rTorrent) are matched by title to that activity
    - Only your downloads appear on your dashboard
 
 ### Multi-Instance Support
@@ -52,7 +55,7 @@ SONARR_INSTANCES=[{"name":"main","url":"...","apiKey":"..."}]
 ## Prerequisites
 
 - **Docker** (recommended), or Node.js (v22+) for manual installation
-- At least one of: SABnzbd or qBittorrent
+- At least one download client: SABnzbd, qBittorrent, Transmission, or rTorrent
 - Sonarr (optional, for TV tracking)
 - Radarr (optional, for movie tracking)
 - Emby (for user authentication)
@@ -107,6 +110,8 @@ docker run -d \
   -e RADARR_INSTANCES='[{"name":"main","url":"http://radarr:7878","apiKey":"your-key"}]' \
   -e SABNZBD_INSTANCES='[{"name":"main","url":"http://sabnzbd:8080","apiKey":"your-key"}]' \
   -e QBITTORRENT_INSTANCES='[{"name":"main","url":"http://qbit:8080","username":"admin","password":"pass"}]' \
+  -e TRANSMISSION_INSTANCES='[{"name":"main","url":"http://transmission:9091","username":"admin","password":"pass"}]' \
+  -e RTORRENT_INSTANCES='[{"name":"main","url":"http://rtorrent:8080/RPC2","username":"rtorrent","password":"rtorrent"}]' \
   -e LOG_LEVEL=info \
   -e POLL_INTERVAL=5000 \
   docker.i3omb.com/sofarr:latest
@@ -130,6 +135,8 @@ services:
       - RADARR_INSTANCES=[{"name":"main","url":"http://radarr:7878","apiKey":"your-key"}]
       - SABNZBD_INSTANCES=[{"name":"main","url":"http://sabnzbd:8080","apiKey":"your-key"}]
       - QBITTORRENT_INSTANCES=[{"name":"main","url":"http://qbit:8080","username":"admin","password":"pass"}]
+      - TRANSMISSION_INSTANCES=[{"name":"main","url":"http://transmission:9091","username":"admin","password":"pass"}]
+      - RTORRENT_INSTANCES=[{"name":"main","url":"http://rtorrent:8080/RPC2","username":"rtorrent","password":"rtorrent"}]
       - LOG_LEVEL=info
       - POLL_INTERVAL=5000
 ```
@@ -187,6 +194,19 @@ POLL_INTERVAL=5000                  # Background polling interval in ms (default
                                     # Set to 0 or "off" to disable (on-demand mode)
 ```
 
+### Download Clients (PDCA)
+
+sofarr uses a **Pluggable Download Client Architecture (PDCA)** that provides a unified interface for all download clients. This enables consistent data normalization, easy addition of new client types, and centralized configuration management.
+
+**Supported Download Clients:**
+
+| Client | Protocol | Auth Method | Notes |
+|--------|----------|-------------|-------|
+| SABnzbd | REST API | API Key | Usenet downloads |
+| qBittorrent | Sync API | Username/Password | BitTorrent with incremental updates |
+| Transmission | JSON-RPC | Username/Password | BitTorrent with session management |
+| rTorrent | XML-RPC | HTTP Basic Auth | BitTorrent, requires the full RPC endpoint in the url field (e.g. /RPC2 or /xmlrpc for whatbox.ca). No path is automatically appended. |
+
 ### Service Instances (JSON Array Format)
 
 All services support multi-instance configuration via single-line JSON arrays:
@@ -198,10 +218,21 @@ SABNZBD_INSTANCES=[{"name":"primary","url":"https://sabnzbd.example.com","apiKey
 # qBittorrent Instances (uses username/password, not API key)
 QBITTORRENT_INSTANCES=[{"name":"main","url":"https://qbittorrent.example.com","username":"admin","password":"secret"}]
 
+# Transmission Instances (uses username/password)
+TRANSMISSION_INSTANCES=[{"name":"main","url":"http://transmission:9091/transmission/rpc","username":"admin","password":"pass"}]
+
+# rTorrent Instances (uses username/password, URL must include full RPC endpoint)
+# Standard installs use /RPC2. Some providers like whatbox.ca use /xmlrpc.
+# No path is automatically appended - always include the full RPC endpoint.
+RTORRENT_INSTANCES=[{"name":"main","url":"http://rtorrent:8080/RPC2","username":"rtorrent","password":"rtorrent"}]
+
+# For whatbox.ca (example):
+# RTORRENT_INSTANCES=[{"name":"whatbox","url":"https://user.whatbox.ca/xmlrpc","username":"user","password":"pass"}]
+
 # Sonarr Instances
 SONARR_INSTANCES=[{"name":"hd","url":"https://sonarr.example.com","apiKey":"your-api-key"}]
 
-# Radarr Instances  
+# Radarr Instances
 RADARR_INSTANCES=[{"name":"movies","url":"https://radarr.example.com","apiKey":"your-api-key"}]
 
 # Emby (single instance for authentication)
@@ -215,6 +246,18 @@ If you only have one instance, you can use the legacy format:
 ```bash
 SABNZBD_URL=https://sabnzbd.example.com
 SABNZBD_API_KEY=your-api-key
+
+QBITTORRENT_URL=https://qbittorrent.example.com
+QBITTORRENT_USERNAME=admin
+QBITTORRENT_PASSWORD=secret
+
+TRANSMISSION_URL=http://transmission:9091/transmission/rpc
+TRANSMISSION_USERNAME=admin
+TRANSMISSION_PASSWORD=pass
+
+RTORRENT_URL=http://rtorrent:8080/RPC2
+RTORRENT_USERNAME=rtorrent
+RTORRENT_PASSWORD=rtorrent
 ```
 
 ## Setting Up User Tags
@@ -263,7 +306,7 @@ sofarr polls all configured services in the background and caches the results. D
 ### For qBittorrent Downloads
 - **Seeds** - Number of seeders
 - **Peers** - Number of peers
-- **Availability** - Percentage available in swarm
+- **Availability** - Percentage available in swarm (shown in red when below 100%)
 
 ## API Endpoints
 
@@ -279,6 +322,10 @@ sofarr polls all configured services in the background and caches the results. D
 - `GET /api/dashboard/user-summary` — Per-user download counts (admin)
 - `GET /api/dashboard/status` — Server / polling / cache status (admin)
 - `GET /api/dashboard/cover-art` — Proxied cover art image
+- `POST /api/dashboard/blocklist-search` — Blocklist a release and trigger a new search (admin or non-admin with eligibility: import issues OR torrent >1h old AND availability<100%)
+
+### History
+- `GET /api/history/recent` — Recently completed downloads from Sonarr/Radarr history
 
 ### Service APIs (proxy to your services)
 - `GET /api/sabnzbd/*` — SABnzbd API proxy
@@ -323,7 +370,7 @@ npm run test:coverage   # with V8 coverage report (outputs to coverage/)
 npm run test:ui         # interactive Vitest UI
 ```
 
-115 tests across 8 test files covering the security-critical paths: auth middleware, CSRF protection, secret sanitization, config parsing, token store, and qBittorrent utilities. See [`tests/README.md`](tests/README.md) for design decisions and coverage targets.
+145 tests across 10 test files covering the security-critical paths: auth middleware, CSRF protection, secret sanitization, config parsing, token store, qBittorrent utilities, and history deduplication/classification. See [`tests/README.md`](tests/README.md) for design decisions and coverage targets.
 
 ## Development
 
@@ -342,3 +389,4 @@ MIT
 ---
 
 *sofarr: See what has downloaded "so far" from the comfort of your "sofa"*
+

SECURITY.md

@@ -4,9 +4,10 @@
 
 | Version | Supported |
 |---------|-----------|
-| 1.0.x   | ✅ Yes    |
-| 0.2.x   | ❌ No     |
-| 0.1.x   | ❌ No     |
+| 1.2.x   | ✅ Yes    |
+| 1.1.x   | ✅ Yes    |
+| 1.0.x   | ❌ No     |
+| < 1.0   | ❌ No     |
 
 ## Reporting a Vulnerability
 
@@ -79,10 +80,10 @@ services:
       - EMBY_API_KEY_FILE=/run/secrets/emby_api_key
 ```
 
-> Note: File-based secret loading requires application code support.
-> Currently sofarr reads secrets from environment variables only.
-> Mounting secrets as env vars (via `environment:` in compose) is the
-> current supported approach.
+> Since v1.2.0, sofarr natively supports the `_FILE` pattern.
+> Set `COOKIE_SECRET_FILE=/run/secrets/cookie_secret` and sofarr will
+> read the secret value from that file at startup. See `docker-compose.yaml`
+> for a complete example.
 
 ---
 

certs/.gitignore

@@ -0,0 +1,6 @@
+# Ignore all cert/key files EXCEPT the bundled snakeoil development defaults.
+# Never commit real TLS certificates or private keys to version control.
+*
+!.gitignore
+!snakeoil.crt
+!snakeoil.key

certs/snakeoil.crt

@@ -0,0 +1,22 @@
+-----BEGIN CERTIFICATE-----
+MIIDoTCCAomgAwIBAgIUPgupZzf+zgMp4ylvf1NBRIWNpeUwDQYJKoZIhvcNAQEL
+BQAwUjELMAkGA1UEBhMCR0IxDjAMBgNVBAgMBUxvY2FsMQ4wDAYDVQQHDAVMb2Nh
+bDEPMA0GA1UECgwGc29mYXJyMRIwEAYDVQQDDAlsb2NhbGhvc3QwHhcNMjYwNTE3
+MDk0NDQ4WhcNMzYwNTE0MDk0NDQ4WjBSMQswCQYDVQQGEwJHQjEOMAwGA1UECAwF
+TG9jYWwxDjAMBgNVBAcMBUxvY2FsMQ8wDQYDVQQKDAZzb2ZhcnIxEjAQBgNVBAMM
+CWxvY2FsaG9zdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAL5Y05DF
+9U3k27SGByJqdbKThRRabX0hsK0zckkbXoaj0U4odZatUicAqkm6yWzpqQyZM6qH
+XX68LXqJk8r2VIdTTtKe5QU1WUAsW6KD0c514YC1VZ3a9ivQ2/tfdQsm8YxM/ECq
+e2XFklfvE72HkHF4fM9LCMS/LeazazF0ogNTkyE27g9Ry/ofR2P4MymLtyBbQ1NA
+B1zYRIhJ5HqFRMszBKhWi1zRgUQQNBuYA5wtxnXA9QNSz6ObtdWStfJ/C1Kuitpe
+OVrB/TKCp1OKBpZTd4mBKlvdJWos9eZPzP4vLnsReT4pHBx6J2Jd1dC97/MAXLYP
+mIXP+04zK5sWRUsCAwEAAaNvMG0wHQYDVR0OBBYEFCpYKb3zMgv4qThe8ukFrVIl
+lhD3MB8GA1UdIwQYMBaAFCpYKb3zMgv4qThe8ukFrVIllhD3MA8GA1UdEwEB/wQF
+MAMBAf8wGgYDVR0RBBMwEYcEfwAAAYIJbG9jYWxob3N0MA0GCSqGSIb3DQEBCwUA
+A4IBAQBQ5Jg0pn4XW/560laNl7XAoGuMwrIy5j6zDlIgFE8DWAb0NGNyu/FkCVIZ
+ruLNktq+w+kTeneAuYW3CGyac2HZo9T60VtQNL/k17hrDw1F6kMpAAYm6aiyFtE9
+Stw07PMvpvjxKvetPLOQsfk0/hh0Nh2PiVVdqvVE/gGoraboHEfH+eGf/Arzg7s4
+CzZTEz0OJP5i7VkZAvFygShPx/gHY77ojeHPl2LN3KI7s43TrjYZjxbUDwWDpGp0
+BIsDFP+9NAvA5I74biChfEEopmBczVbQRtqBxBX1JTa2aT5w/ifUNyKVKIGp49Q8
+o59gDmbCXhypom7OsyxBLZgyVWU1
+-----END CERTIFICATE-----

certs/snakeoil.key

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC+WNOQxfVN5Nu0
+hgcianWyk4UUWm19IbCtM3JJG16Go9FOKHWWrVInAKpJusls6akMmTOqh11+vC16
+iZPK9lSHU07SnuUFNVlALFuig9HOdeGAtVWd2vYr0Nv7X3ULJvGMTPxAqntlxZJX
+7xO9h5BxeHzPSwjEvy3ms2sxdKIDU5MhNu4PUcv6H0dj+DMpi7cgW0NTQAdc2ESI
+SeR6hUTLMwSoVotc0YFEEDQbmAOcLcZ1wPUDUs+jm7XVkrXyfwtSroraXjlawf0y
+gqdTigaWU3eJgSpb3SVqLPXmT8z+Ly57EXk+KRwceidiXdXQve/zAFy2D5iFz/tO
+MyubFkVLAgMBAAECggEAEk0RCyNCJBSdqSKWLtFq8o0rdBsDpugyOymuOQHOjOxu
+oQo6NnWaNF5kgQVAyfd0EpGFfavyw2iNVaUPo1zoU9ogwuOWSnHOj64UIcp0+PN6
+VHknohWqdukBLyiGfnJM/0ieaKTbi2i7dGsfDA+rxbUoO6s2GYPC6O9inlUqVJGU
+fBXKTbCneW1+hJQFcOKPW2+qwiUxbudG9neNTYFOm9a7Bfa6MLJ22mkfYVrHYDzo
+gESo8sHXbEtvemka9jN0N/GoXgUi7iFXbqslPUoakCF7sgG0cXuUM9duSt67ynLj
+j7Ix+QiKAZgvSO/83b7vK74Xmd6XFUif41VMZ2iEGQKBgQDqp/ZSCAakarRpBRN4
+psKuhaYiBKurb5GezTOSfEGWxmng2s0bHcx74alKKNN8Tu2mNx6yafQdRNQdM+fG
+dn8JnQUGXYpGwQbLHZ/aO0M64WBxfQku4JNGh+VZ3ZyUC+So28vzCYqx8qwJi94L
+2sF8787hzHO1INzVaeXzQ89pEwKBgQDPqRzsJsP+zZmA4x16CtoWY7Z1d4z0GTkA
+erlXNinu76AIvra6aUld/65ymMyNIIpLZoci55ZGxBY7g8U29e10iT+xmxAgq3VT
+Tn438MbDXEgA+HvdRXCFPvNQQk0ZDegazdhTdtuhj+IHcm4M94zfVM3MSJOr0hJf
+JGaVIGEx6QKBgDZLftckPEU221+haQv1qf4vtm0Qn5gfTJZt7Izsa1CzwDPi7Kpl
+jrbrU/xwzd5pdNuMzXGCypUrI9lN9Ucai/JxfoQmiKQubZ/5zs7z/25UT7hysflC
+xVEAiLTubhhjWBkqIlqtzoW2HNBoqIwdpb9+zWO5ptw2KmLHCgnrmsY5AoGBAKOt
+YCaix4lm9L8qRGmVdCCBp6ce+/LKjqtaEAw1nQe/yBwcdlqn8jQs+4tH9LKoG1kj
+DxDsCP7uP7fZPPD9FpTsOU/8MNIPUwK+s63UElaZvgdF1BusR+w+mfmAyNQeqfu2
+k/P1k1fc2QOVpjiCRn8hkLSb4AlmIyTqxBB23SVBAoGATMtuk1r+SS9SDJW73CI1
+jLkJkPGrBvX0dFZGtedpwLVhUTDnqKIsy2F1iGDRGIAy5IAiLEFx44qQrhUau7zR
+/2avY0Ua9To9LW0k/matzJUKvXxYm59jh/GDp6LFU89hsL2zSd6z0Aknvh1SryCb
+OSbN8wfCz53+7qea4NQEB4E=
+-----END PRIVATE KEY-----

client/src/App.jsx

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 import { useState, useEffect } from 'react';
 import axios from 'axios';
 import './App.css';

client/src/main.jsx

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import App from './App.jsx'

client/vite.config.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 

docker-compose.yaml

@@ -4,15 +4,25 @@ services:
     container_name: sofarr
     restart: unless-stopped
     ports:
-      - "127.0.0.1:3001:3001"   # bind to loopback only — expose via reverse proxy
+      # Direct HTTPS (default — uses bundled snakeoil cert if TLS_CERT not set)
+      - "3001:3001"
+      # Uncomment the line below and comment out the above to bind to loopback
+      # only when using a reverse proxy (set TLS_ENABLED=false in that case):
+      # - "127.0.0.1:3001:3001"
     environment:
       - PORT=3001
       - NODE_ENV=production
       - LOG_LEVEL=info
-      # Set to 1 when running behind a reverse proxy (Nginx, Caddy, Traefik)
-      # so Express trusts X-Forwarded-For and X-Forwarded-Proto headers.
-      - TRUST_PROXY=1
-      # --- Replace placeholders with real values or use Docker secrets ---
+      # --- TLS ---
+      # Default: TLS enabled using bundled snakeoil cert (self-signed).
+      # Supply your own cert/key by mounting them and setting these paths:
+      # - TLS_CERT=/app/certs/server.crt
+      # - TLS_KEY=/app/certs/server.key
+      # Set TLS_ENABLED=false if terminating TLS at a reverse proxy instead.
+      # If using a reverse proxy, also set TRUST_PROXY=1 below.
+      # - TRUST_PROXY=1
+      # --- Secrets: use _FILE variants (Docker secrets) in production -------
+      # Option A — plain environment variables (simple, less secure):
       - COOKIE_SECRET=change-me-generate-with-openssl-rand-hex-32
       - EMBY_URL=https://emby.example.com
       - EMBY_API_KEY=your-emby-api-key
@@ -20,9 +30,23 @@ services:
       - RADARR_INSTANCES=[{"name":"main","url":"https://radarr.example.com","apiKey":"your-radarr-api-key"}]
       - SABNZBD_INSTANCES=[{"name":"main","url":"https://sabnzbd.example.com","apiKey":"your-sabnzbd-api-key"}]
       - QBITTORRENT_INSTANCES=[{"name":"main","url":"https://qbittorrent.example.com","username":"admin","password":"your-password"}]
+      # Option B — Docker secrets (_FILE pattern, recommended for production):
+      # Uncomment the lines below and comment out Option A above.
+      # Create secret files with: echo -n "value" > ./secrets/cookie_secret.txt
+      # - COOKIE_SECRET_FILE=/run/secrets/cookie_secret
+      # - EMBY_API_KEY_FILE=/run/secrets/emby_api_key
+      # - SONARR_API_KEY_FILE=/run/secrets/sonarr_api_key   # legacy single-instance only
+      # - RADARR_API_KEY_FILE=/run/secrets/radarr_api_key   # legacy single-instance only
+      # - SABNZBD_API_KEY_FILE=/run/secrets/sabnzbd_api_key # legacy single-instance only
+    # secrets:                      # uncomment when using Option B
+    #   - cookie_secret
+    #   - emby_api_key
     volumes:
-      # Persistent volume for SQLite token store and log file
+      # Persistent volume for token store and log file
       - sofarr-data:/app/data
+      # Mount your own TLS certificate and key (optional — snakeoil used if omitted)
+      # - /path/to/your/server.crt:/app/certs/server.crt:ro
+      # - /path/to/your/server.key:/app/certs/server.key:ro
     # Run as the built-in non-root 'node' user (UID/GID 1000)
     user: "1000:1000"
     # Read-only root filesystem; only the data volume is writable
@@ -35,7 +59,9 @@ services:
       - ALL                     # drop all Linux capabilities
     cap_add: []                 # add back none — Node.js needs no special caps
     healthcheck:
-      test: ["CMD", "wget", "-qO-", "http://localhost:3001/health"]
+      # Respects TLS_ENABLED: uses http when set to false, https otherwise.
+      # --no-check-certificate handles self-signed / snakeoil certs.
+      test: ["CMD", "/bin/sh", "-c", "[ \"${TLS_ENABLED:-true}\" = \"false\" ] && wget -qO- http://localhost:${PORT:-3001}/health || wget -qO- --no-check-certificate https://localhost:${PORT:-3001}/health"]
       interval: 30s
       timeout: 5s
       retries: 3
@@ -43,3 +69,10 @@ services:
 
 volumes:
   sofarr-data:
+
+# Docker secrets definitions (uncomment and populate when using Option B above)
+# secrets:
+#   cookie_secret:
+#     file: ./secrets/cookie_secret.txt
+#   emby_api_key:
+#     file: ./secrets/emby_api_key.txt

docs/ADDING-A-DOWNLOAD-CLIENT.md

@@ -0,0 +1,399 @@
+# Adding a New Download Client to Sofarr
+
+This guide explains how to add support for a new download client to Sofarr using the Pluggable Download Client Architecture (PDCA).
+
+## Overview
+
+The PDCA makes adding new download clients straightforward by providing a standardized interface. You only need to implement the `DownloadClient` abstract base class and register your client in the configuration system.
+
+## Prerequisites
+
+- Familiarity with JavaScript/Node.js
+- Understanding of your target client's API
+- Basic knowledge of Sofarr's architecture (see [ARCHITECTURE.md](ARCHITECTURE.md))
+
+## Step 1: Create the Client Class
+
+Create a new file in `server/clients/` named after your client (e.g., `DelugeClient.js`).
+
+```javascript
+// server/clients/DelugeClient.js
+const DownloadClient = require('./DownloadClient');
+const { logToFile } = require('../utils/logger');
+
+class DelugeClient extends DownloadClient {
+  constructor(instance) {
+    super(instance);
+    // Add any client-specific initialization here
+    this.sessionId = null;
+    this.rpcUrl = `${this.url}/json`;
+  }
+
+  getClientType() {
+    return 'deluge';
+  }
+
+  async testConnection() {
+    try {
+      // Implement connection test logic
+      const response = await this.makeRequest('auth.check_session');
+      logToFile(`[Deluge:${this.name}] Connection test successful`);
+      return true;
+    } catch (error) {
+      logToFile(`[Deluge:${this.name}] Connection test failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  async makeRequest(method, params = []) {
+    // Implement RPC call logic
+    const payload = {
+      method: method,
+      params: params,
+      id: Date.now()
+    };
+
+    // Add authentication if needed
+    if (this.sessionId) {
+      payload.params.unshift(this.sessionId);
+    }
+
+    // Make HTTP request to your client's API
+    // Handle authentication, errors, etc.
+  }
+
+  async getActiveDownloads() {
+    try {
+      // Fetch downloads from your client
+      const torrents = await this.makeRequest('core.get_torrents_status', 
+        [{}, ['name', 'state', 'progress', 'total_size', 'download_payload_rate']]
+      );
+
+      // Normalize each download using the standard schema
+      return Object.entries(torrents).map(([id, torrent]) => 
+        this.normalizeDownload({ ...torrent, id })
+      );
+    } catch (error) {
+      logToFile(`[Deluge:${this.name}] Error fetching downloads: ${error.message}`);
+      return [];
+    }
+  }
+
+  async getClientStatus() {
+    try {
+      // Optional: Return client status information
+      const status = await this.makeRequest('core.get_session_status');
+      return status;
+    } catch (error) {
+      logToFile(`[Deluge:${this.name}] Error getting client status: ${error.message}`);
+      return null;
+    }
+  }
+
+  normalizeDownload(torrent) {
+    // Convert client-specific data to the normalized schema
+    return {
+      id: torrent.id,
+      title: torrent.name,
+      type: 'torrent',
+      client: 'deluge',
+      instanceId: this.id,
+      instanceName: this.name,
+      status: this.mapStatus(torrent.state),
+      progress: Math.round(torrent.progress * 100),
+      size: torrent.total_size,
+      downloaded: Math.round(torrent.total_size * torrent.progress),
+      speed: torrent.download_payload_rate,
+      eta: torrent.eta > 0 ? torrent.eta : null,
+      category: torrent.label || undefined,
+      tags: torrent.tracker ? [torrent.tracker] : [],
+      savePath: torrent.save_path,
+      addedOn: torrent.added_time ? new Date(torrent.added_time * 1000).toISOString() : undefined,
+      raw: torrent // Include original data for advanced use cases
+    };
+  }
+
+  mapStatus(state) {
+    // Map client-specific states to normalized statuses
+    const statusMap = {
+      'Downloading': 'Downloading',
+      'Seeding': 'Seeding',
+      'Paused': 'Paused',
+      'Checking': 'Checking',
+      'Error': 'Error',
+      'Queued': 'Queued'
+    };
+    
+    return statusMap[state] || state;
+  }
+}
+
+module.exports = DelugeClient;
+```
+
+## Step 2: Add Configuration Support
+
+Update `server/utils/config.js` to add support for your client's environment variables:
+
+```javascript
+function getDelugeInstances() {
+  return parseInstances(
+    process.env.DELUGE_INSTANCES,
+    process.env.DELUGE_URL,
+    null, // no apiKey for Deluge
+    process.env.DELUGE_USERNAME,
+    process.env.DELUGE_PASSWORD
+  );
+}
+
+// Add to module.exports
+module.exports = {
+  // ... existing exports
+  getDelugeInstances,
+  // ... other exports
+};
+```
+
+## Step 3: Register the Client
+
+Update `server/utils/downloadClients.js` to include your client:
+
+```javascript
+const DelugeClient = require('../clients/DelugeClient');
+
+// Add to clientClasses mapping
+const clientClasses = {
+  sabnzbd: SABnzbdClient,
+  qbittorrent: QBittorrentClient,
+  transmission: TransmissionClient,
+  deluge: DelugeClient // Add your client here
+};
+
+// Update instance configuration
+const instanceConfigs = [
+  ...sabnzbdInstances.map(inst => ({ ...inst, type: 'sabnzbd' })),
+  ...qbittorrentInstances.map(inst => ({ ...inst, type: 'qbittorrent' })),
+  ...transmissionInstances.map(inst => ({ ...inst, type: 'transmission' })),
+  ...delugeInstances.map(inst => ({ ...inst, type: 'deluge' })) // Add this line
+];
+```
+
+## Step 4: Update Poller Integration
+
+The poller automatically uses the registry, so no changes are needed there. However, if you want to maintain backward compatibility with existing cache keys, you may need to update the poller's transformation logic.
+
+## Step 5: Add Tests
+
+Create comprehensive tests for your client:
+
+```javascript
+// tests/unit/clients/DelugeClient.test.js
+const DelugeClient = require('../../../server/clients/DelugeClient');
+
+describe('DelugeClient', () => {
+  let client;
+  let mockConfig;
+
+  beforeEach(() => {
+    mockConfig = {
+      id: 'test-deluge',
+      name: 'Test Deluge',
+      url: 'http://localhost:8112',
+      username: 'admin',
+      password: 'deluge'
+    };
+    
+    client = new DelugeClient(mockConfig);
+  });
+
+  describe('Constructor', () => {
+    it('should initialize with correct properties', () => {
+      expect(client.getClientType()).toBe('deluge');
+      expect(client.getInstanceId()).toBe('test-deluge');
+      expect(client.name).toBe('Test Deluge');
+    });
+  });
+
+  describe('Connection Test', () => {
+    it('should test connection successfully', async () => {
+      // Mock successful connection
+      client.makeRequest = jest.fn().mockResolvedValue({ result: true });
+      
+      const result = await client.testConnection();
+      
+      expect(result).toBe(true);
+      expect(client.makeRequest).toHaveBeenCalledWith('auth.check_session');
+    });
+  });
+
+  describe('Download Normalization', () => {
+    it('should normalize download data correctly', () => {
+      const torrent = {
+        id: 'abc123',
+        name: 'Test Torrent',
+        state: 'Downloading',
+        progress: 0.75,
+        total_size: 1000000000,
+        download_payload_rate: 1048576,
+        eta: 3600,
+        label: 'movies',
+        save_path: '/downloads/test'
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized).toEqual({
+        id: 'abc123',
+        title: 'Test Torrent',
+        type: 'torrent',
+        client: 'deluge',
+        instanceId: 'test-deluge',
+        instanceName: 'Test Deluge',
+        status: 'Downloading',
+        progress: 75,
+        size: 1000000000,
+        downloaded: 750000000,
+        speed: 1048576,
+        eta: 3600,
+        category: 'movies',
+        tags: [],
+        savePath: '/downloads/test',
+        raw: torrent
+      });
+    });
+  });
+
+  // Add more tests for error handling, edge cases, etc.
+});
+```
+
+## Step 6: Configuration Examples
+
+Add documentation for your client's configuration in `.env.sample`:
+
+```bash
+# Deluge Configuration
+# Single instance (legacy format)
+# DELUGE_URL=http://localhost:8112
+# DELUGE_USERNAME=admin
+# DELUGE_PASSWORD=deluge
+
+# Multiple instances (JSON format)
+DELUGE_INSTANCES='[
+  {
+    "name": "Main Deluge",
+    "url": "http://localhost:8112",
+    "username": "admin",
+    "password": "deluge"
+  },
+  {
+    "name": "Backup Deluge",
+    "url": "http://localhost:8113",
+    "username": "admin",
+    "password": "deluge"
+  }
+]'
+```
+
+## Step 7: Update Documentation
+
+Update relevant documentation files:
+
+1. **ARCHITECTURE.md**: Add your client to the download clients section
+2. **README.md**: Add configuration instructions for your client
+3. **CHANGELOG.md**: Document the new client support
+
+## Best Practices
+
+### Error Handling
+
+- Always wrap API calls in try-catch blocks
+- Return empty arrays for download fetch failures
+- Log errors with appropriate context
+- Implement retry logic where appropriate
+
+### Authentication
+
+- Store credentials securely (don't log them)
+- Handle session expiration gracefully
+- Implement automatic re-authentication when possible
+
+### Performance
+
+- Use efficient API calls (batch requests when available)
+- Implement caching for expensive operations
+- Consider pagination for large download lists
+- Use connection pooling for HTTP clients
+
+### Normalization
+
+- Always return the complete normalized schema
+- Handle missing or null values gracefully
+- Preserve original data in the `raw` field
+- Map client-specific statuses to standard ones
+
+### Testing
+
+- Test both success and failure scenarios
+- Mock external API calls
+- Test normalization edge cases
+- Include integration tests
+
+## Example: Complete Implementation
+
+For a complete example, refer to the existing client implementations:
+
+- **SABnzbdClient.js**: Simple REST API client
+- **QBittorrentClient.js**: Complex client with sync API and fallback
+- **TransmissionClient.js**: JSON-RPC client with session management
+- **RTorrentClient.js**: XML-RPC client with HTTP Basic Auth
+
+### rTorrent Specific Notes
+
+rTorrent uses XML-RPC over HTTP with the following specifics:
+
+- **Endpoint**: `${url}/RPC2` (most common)
+- **Authentication**: HTTP Basic Auth (handled by reverse proxy or web server)
+- **Primary Method**: `d.multicall2` for efficient bulk torrent data retrieval
+- **Library**: Uses the `xmlrpc` package (v1.3.2)
+- **Status Mapping**: Combines `d.state`, `d.is_active`, and `d.is_hash_checking` to determine status
+- **ETA Calculation**: Computed from download speed and remaining bytes when actively downloading
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication failures**: Check credentials and URL format
+2. **API changes**: Ensure your client matches the API version
+3. **Network issues**: Implement proper timeout and retry logic
+4. **Data normalization**: Verify all required fields are populated
+
+### Debugging
+
+- Enable debug logging in your client
+- Check the server logs for error messages
+- Use the test connection endpoint to verify configuration
+- Test API calls manually before implementing
+
+## Contributing
+
+When contributing a new client:
+
+1. Follow the existing code style and patterns
+2. Include comprehensive tests
+3. Update all relevant documentation
+4. Test with multiple instances if supported
+5. Consider edge cases and error scenarios
+
+## Support
+
+If you need help implementing a new client:
+
+1. Review existing client implementations
+2. Check the architecture documentation
+3. Look at the test examples
+4. Ask questions in the project discussions
+
+---
+
+*This guide covers the basics of adding a new download client. For more advanced scenarios, refer to the source code and existing implementations.*

docs/diagrams/activity-matching.puml

@@ -1,156 +0,0 @@
-@startuml activity-matching
-!theme plain
-title sofarr — Download Matching Activity Diagram
-
-start
-
-:Read cached data from MemoryCache;
-note right
-  poll:sab-queue, poll:sab-history,
-  poll:sonarr-queue, poll:sonarr-history,
-  poll:radarr-queue, poll:radarr-history,
-  poll:sonarr-tags, poll:radarr-tags,
-  poll:qbittorrent
-end note
-
-:Build **seriesMap** from Sonarr queue records
-(seriesId → embedded series object);
-
-:Build **moviesMap** from Radarr queue records
-(movieId → embedded movie object);
-
-:Build **sonarrTagMap** (tagId → label)
-Build **radarrTagMap** (tagId → label);
-
-if (showAll?) then (yes)
-  :Fetch full Emby user list
-  Build **embyUserMap** (lowerName → displayName)
-  [cached 60s];  
-endif
-
-:Initialise **userDownloads** = [];
-
-partition "Process SABnzbd Queue Slots" {
-  while (More queue slots?) is (yes)
-    :Get slot filename (nzbName);
-    :nzbNameLower = nzbName.toLowerCase();
-
-    if (Title matches Sonarr **queue** record?) then (yes)
-      :series = seriesMap.get(match.seriesId)\n|| match.series;
-      if (series exists?) then (yes)
-        :allTags = extractAllTags(series.tags, sonarrTagMap)
-matchedUserTag = extractUserTag(series.tags, sonarrTagMap, username);
-        if (showAll AND hasAnyTag?) then (yes)
-          :Build download object (type=series)
-          Add coverArt, status, progress, speed, eta
-          Add allTags, matchedUserTag
-          Add tagBadges = buildTagBadges(allTags, embyUserMap)
-          Add importIssues if any
-          Add admin fields (paths, arrLink);
-          :Push to **userDownloads**;
-        elseif (NOT showAll AND matchedUserTag?) then (yes)
-          :Build download object (type=series)
-          Add matchedUserTag;
-          :Push to **userDownloads**;
-        endif
-      endif
-    endif
-
-    if (Title matches Radarr **queue** record?) then (yes)
-      :movie = moviesMap.get(match.movieId)\n|| match.movie;
-      if (movie exists?) then (yes)
-        :allTags = extractAllTags(movie.tags, radarrTagMap)
-matchedUserTag = extractUserTag(movie.tags, radarrTagMap, username);
-        if (showAll AND hasAnyTag?) then (yes)
-          :Build download object (type=movie)
-          Add coverArt, status, progress, speed, eta
-          Add allTags, matchedUserTag, tagBadges
-          Add importIssues if any
-          Add admin fields (paths, arrLink);
-          :Push to **userDownloads**;
-        elseif (NOT showAll AND matchedUserTag?) then (yes)
-          :Build download object (type=movie)
-          Add matchedUserTag;
-          :Push to **userDownloads**;
-        endif
-      endif
-    endif
-  endwhile (no)
-}
-
-partition "Process SABnzbd History Slots" {
-  while (More history slots?) is (yes)
-    :Get slot name (nzbName);
-    :nzbNameLower = nzbName.toLowerCase();
-
-    if (Title matches Sonarr **history** record?) then (yes)
-      :series = seriesMap.get(match.seriesId)\n|| match.series;
-      if (series found?) then (yes)
-        :extractAllTags + extractUserTag(username)
-Build download (type=series, completedAt)
-Add allTags, matchedUserTag, tagBadges if showAll;
-        :Push to **userDownloads** if showAll+anyTag or matchedUserTag;
-      endif
-    endif
-
-    if (Title matches Radarr **history** record?) then (yes)
-      :movie = moviesMap.get(match.movieId)\n|| match.movie;
-      if (movie found?) then (yes)
-        :extractAllTags + extractUserTag(username)
-Build download (type=movie, completedAt)
-Add allTags, matchedUserTag, tagBadges if showAll;
-        :Push to **userDownloads** if showAll+anyTag or matchedUserTag;
-      endif
-    endif
-  endwhile (no)
-}
-
-partition "Process qBittorrent Torrents" {
-  while (More torrents?) is (yes)
-    :Get torrent name;
-    :torrentNameLower = name.toLowerCase();
-
-    if (Matches Sonarr **queue**?) then (yes)
-      :Resolve series → check tag;
-      :mapTorrentToDownload() + enrich;
-      :Push if matches → **continue**;
-    elseif (Matches Radarr **queue**?) then (yes)
-      :Resolve movie → check tag;
-      :mapTorrentToDownload() + enrich;
-      :Push if matches → **continue**;
-    elseif (Matches Sonarr **history**?) then (yes)
-      :Resolve series via seriesMap;
-      :mapTorrentToDownload() + enrich;
-      :Push if matches → **continue**;
-    elseif (Matches Radarr **history**?) then (yes)
-      :Resolve movie via moviesMap;
-      :mapTorrentToDownload() + enrich;
-      :Push if matches → **continue**;
-    else (no match)
-      :Skip torrent (unmatched);
-    endif
-  endwhile (no)
-}
-
-:Return JSON response
-{ user, isAdmin, downloads: userDownloads };
-
-stop
-
-legend right
-  **Title Matching Logic**
-  (bidirectional substring, case-insensitive):
-  ""rTitle.includes(dlTitle) || dlTitle.includes(rTitle)""
-
-  **Tag Matching Logic** (tagMatchesUser):
-  1. Exact: tag.toLowerCase() === username
-  2. Sanitised: sanitizeTagLabel(tag) === sanitizeTagLabel(username)
-     (handles Ombi-mangled email-style usernames)
-
-  **extractAllTags**: returns all resolved tag labels
-  **extractUserTag**: returns the ONE label matching current user
-  **buildTagBadges**: classifies each tag against full Emby user
-    list → { label, matchedUser: displayName | null }
-end legend
-
-@enduml

docs/diagrams/class-data.puml

@@ -1,230 +0,0 @@
-@startuml class-data
-!theme plain
-title sofarr — Data Model Diagram
-
-skinparam classAttributeIconSize 0
-
-package "External API Responses" {
-  class "SABnzbd Queue Slot" as sabq {
-    + filename : string
-    + nzbname : string
-    + percentage : string
-    + mb : string
-    + mbmissing : string
-    + size : string
-    + timeleft : string
-    + status : string
-    + storage : string
-  }
-
-  class "SABnzbd History Slot" as sabh {
-    + name : string
-    + nzb_name : string
-    + nzbname : string
-    + status : string
-    + size : string
-    + completed_time : string
-    + storage : string
-  }
-
-  class "Sonarr Queue Record" as sqr {
-    + id : number
-    + seriesId : number
-    + series : SonarrSeries
-    + title : string
-    + sourceTitle : string
-    + trackedDownloadStatus : string
-    + trackedDownloadState : string
-    + statusMessages : StatusMessage[]
-    + errorMessage : string
-  }
-
-  class "Sonarr History Record" as shr {
-    + id : number
-    + seriesId : number
-    + title : string
-    + sourceTitle : string
-    + eventType : string
-  }
-
-  class "SonarrSeries" as ss {
-    + id : number
-    + title : string
-    + titleSlug : string
-    + path : string
-    + tags : number[]
-    + images : Image[]
-    + _instanceUrl : string
-  }
-
-  class "Radarr Queue Record" as rqr {
-    + id : number
-    + movieId : number
-    + movie : RadarrMovie
-    + title : string
-    + sourceTitle : string
-    + trackedDownloadStatus : string
-    + trackedDownloadState : string
-    + statusMessages : StatusMessage[]
-    + errorMessage : string
-  }
-
-  class "Radarr History Record" as rhr {
-    + id : number
-    + movieId : number
-    + title : string
-    + sourceTitle : string
-    + eventType : string
-  }
-
-  class "RadarrMovie" as rm {
-    + id : number
-    + title : string
-    + titleSlug : string
-    + path : string
-    + tags : number[]
-    + images : Image[]
-    + _instanceUrl : string
-  }
-
-  class "Tag" as tag {
-    + id : number
-    + label : string
-  }
-
-  class "Image" as img {
-    + coverType : string
-    + remoteUrl : string
-    + url : string
-  }
-
-  class "StatusMessage" as sm {
-    + title : string
-    + messages : string[]
-  }
-
-  class "qBittorrent Torrent" as qbt {
-    + name : string
-    + hash : string
-    + size : number
-    + completed : number
-    + progress : number (0-1)
-    + state : string
-    + dlspeed : number
-    + eta : number
-    + num_seeds : number
-    + num_leechs : number
-    + availability : number
-    + category : string
-    + tags : string
-    + save_path : string
-    + content_path : string
-    + instanceId : string
-    + instanceName : string
-  }
-
-  class "Emby User" as eu {
-    + Id : string
-    + Name : string
-    + Policy : { IsAdministrator: boolean }
-  }
-
-  sqr *-- ss : embedded\n(includeSeries)
-  rqr *-- rm : embedded\n(includeMovie)
-  sqr *-- sm
-  rqr *-- sm
-  ss *-- img
-  rm *-- img
-}
-
-package "sofarr Internal Models" {
-  class "Download Object" as dl {
-    + type : 'series' | 'movie' | 'torrent'
-    + title : string
-    + coverArt : string | null
-    + status : string
-    + progress : string
-    + mb : string
-    + mbmissing : string
-    + size : string
-    + speed : string
-    + eta : string
-    + seriesName : string | null
-    + movieName : string | null
-    + episodeInfo : object | null
-    + movieInfo : object | null
-    + allTags : string[]
-    + matchedUserTag : string | null
-    + tagBadges : TagBadge[] | undefined
-    + importIssues : string[] | null
-    + downloadPath : string | null
-    + targetPath : string | null
-    + arrLink : string | null
-    + qbittorrent : boolean
-    + seeds : number
-    + peers : number
-    + availability : string
-    + rawSize : number
-    + rawSpeed : number
-    + rawEta : number
-    + hash : string
-    + category : string
-    + completedAt : string
-  }
-
-  class "TagBadge" as tagbadge <<value>> {
-    + label : string
-    + matchedUser : string | null
-  }
-
-  class "API Response\n/user-downloads" as apir {
-    + user : string
-    + isAdmin : boolean
-    + downloads : Download[]
-  }
-
-  class "Status Response\n/status" as statr {
-    + server : ServerInfo
-    + polling : PollingInfo
-    + cache : CacheStats
-    + clients : ClientInfo[]
-  }
-
-  class "ServerInfo" as si {
-    + uptimeSeconds : number
-    + nodeVersion : string
-    + memoryUsageMB : number
-    + heapUsedMB : number
-    + heapTotalMB : number
-  }
-
-  class "PollingInfo" as pi {
-    + enabled : boolean
-    + intervalMs : number
-    + lastPoll : PollTimings
-  }
-
-  class "Session Cookie\nemby_user" as cookie {
-    + id : string
-    + name : string
-    + isAdmin : boolean
-    ' Note: Emby AccessToken intentionally excluded
-  }
-
-  apir *-- dl
-  statr *-- si
-  statr *-- pi
-}
-
-' Data flow connections
-sabq ..> dl : matched &\ntransformed
-sabh ..> dl : matched &\ntransformed
-qbt ..> dl : mapTorrentToDownload()
-ss ..> dl : coverArt, seriesName,\npath, tags
-rm ..> dl : coverArt, movieName,\npath, tags
-tag ..> dl : allTags / matchedUserTag
-eu ..> cookie : login creates
-eu ..> tagbadge : buildTagBadges()
-dl *-- tagbadge : tagBadges[]
-
-@enduml

docs/diagrams/class-server.puml

@@ -1,278 +0,0 @@
-@startuml class-server
-!theme plain
-title sofarr — Server Class / Module Diagram
-
-package "server/index.js" as entry {
-  class "EntryPoint" as ep <<module>> {
-    - LOG_LEVELS : Object
-    - currentLevel : number
-    - logFile : WriteStream
-    + shouldLog(level) : boolean
-    --
-    Logging setup, app.listen(),
-    static files, startPoller()
-  }
-}
-
-package "server/app.js" as appfactory {
-  class "createApp(options?)" as appfn <<factory>> {
-    + createApp(skipRateLimits?) : Express
-    --
-    Mounts helmet (CSP nonce),
-    rate limiters, cookie-parser,
-    auth routes (pre-CSRF),
-    verifyCsrf, all other routes,
-    /health, /ready, error handler
-  }
-}
-
-package "server/routes" {
-  class "auth.js" as auth <<router>> {
-    + POST /login (rate-limited)
-    + GET /me
-    + GET /csrf
-    + POST /logout
-    --
-    Authenticates via Emby API
-    Issues emby_user + csrf_token cookies
-    Stores/revokes Emby tokens server-side
-  }
-
-  class "dashboard.js" as dashboard <<router>> {
-    - activeClients : Map<string, ClientInfo>
-    - CLIENT_STALE_MS : 30000
-    --
-    + GET /stream (SSE, text/event-stream)
-    + GET /user-downloads
-    + GET /user-summary
-    + GET /status
-    + GET /cover-art
-    --
-    - getCoverArt(item) : string|null
-    - extractAllTags(tags, tagMap) : string[]
-    - extractUserTag(tags, tagMap, username) : string|null
-    - buildTagBadges(allTags, embyUserMap) : TagBadge[]
-    - getEmbyUsers() : Promise<Map>
-    - sanitizeTagLabel(input) : string
-    - tagMatchesUser(tag, username) : boolean
-    - getImportIssues(record) : string[]|null
-    - getSonarrLink(series) : string|null
-    - getRadarrLink(movie) : string|null
-    - getActiveClients() : ClientInfo[]
-  }
-
-  class "emby.js" as emby_r <<router>> {
-    + GET /sessions
-    + GET /users/:id
-    + GET /users
-    + GET /session/:sessionId/user
-  }
-
-  class "sabnzbd.js" as sab_r <<router>> {
-    + GET /queue
-    + GET /history
-  }
-
-  class "sonarr.js" as sonarr_r <<router>> {
-    + GET /queue
-    + GET /history
-    + GET /series/:id
-    + GET /series
-  }
-
-  class "radarr.js" as radarr_r <<router>> {
-    + GET /queue
-    + GET /history
-    + GET /movies/:id
-    + GET /movies
-  }
-}
-
-package "server/middleware" {
-  class "requireAuth.js" as requireauth <<middleware>> {
-    + requireAuth(req, res, next) : void
-    --
-    Reads emby_user cookie (signed if COOKIE_SECRET)
-    Validates schema: id, name, isAdmin
-    Attaches user to req.user
-    Returns 401 if absent/tampered/invalid
-  }
-
-  class "verifyCsrf.js" as verifycsrf <<middleware>> {
-    + verifyCsrf(req, res, next) : void
-    --
-    Exempt: GET, HEAD, OPTIONS
-    Compares csrf_token cookie
-    vs X-CSRF-Token header
-    using crypto.timingSafeEqual
-    Returns 403 on mismatch/missing
-  }
-}
-
-package "server/utils" {
-  class "MemoryCache" as cache {
-    - store : Map<string, CacheEntry>
-    + get(key) : any|null
-    + set(key, value, ttlMs) : void
-    + invalidate(key) : void
-    + clear() : void
-    + getStats() : CacheStats
-  }
-
-  class "CacheEntry" as ce <<value>> {
-    + value : any
-    + expiresAt : number
-  }
-
-  class "CacheStats" as cs <<value>> {
-    + entryCount : number
-    + totalSizeBytes : number
-    + entries : CacheEntryStats[]
-  }
-
-  class "Poller" as poller <<module>> {
-    - POLL_INTERVAL : number
-    - POLLING_ENABLED : boolean
-    - polling : boolean
-    - lastPollTimings : PollTimings|null
-    - intervalHandle : number|null
-    --
-    + startPoller() : void
-    + stopPoller() : void
-    + pollAllServices() : Promise<void>
-    + getLastPollTimings() : PollTimings|null
-    --
-    - timed(label, fn) : TimedResult
-  }
-
-  class "PollTimings" as pt <<value>> {
-    + totalMs : number
-    + timestamp : string (ISO)
-    + tasks : { label, ms }[]
-  }
-
-  class "Config" as config <<module>> {
-    + getSABnzbdInstances() : Instance[]
-    + getSonarrInstances() : Instance[]
-    + getRadarrInstances() : Instance[]
-    + getQbittorrentInstances() : Instance[]
-    --
-    - parseInstances(envVar, ...) : Instance[]
-  }
-
-  class "Instance" as inst <<value>> {
-    + id : string
-    + name : string
-    + url : string
-    + apiKey : string
-    + username? : string
-    + password? : string
-  }
-
-  class "QBittorrentClient" as qbt {
-    - id : string
-    - name : string
-    - url : string
-    - username : string
-    - password : string
-    - authCookie : string|null
-    --
-    + login() : Promise<boolean>
-    + makeRequest(endpoint, config) : Promise<Response>
-    + getTorrents() : Promise<Torrent[]>
-  }
-
-  class "qbittorrent.js" as qbt_mod <<module>> {
-    - persistedClients : QBittorrentClient[]|null
-    --
-    + getTorrents() : Promise<Torrent[]>
-    + getClients() : QBittorrentClient[]
-    + mapTorrentToDownload(torrent) : Download
-    + formatBytes(bytes) : string
-    + formatSpeed(bps) : string
-    + formatEta(seconds) : string
-  }
-
-  class "Logger" as logger <<module>> {
-    - logFile : WriteStream
-    + logToFile(message) : void
-  }
-
-  class "TokenStore" as tokenstore <<module>> {
-    - store : Object (in-memory)
-    - STORE_PATH : string (DATA_DIR/tokens.json)
-    - TOKEN_TTL_MS : 31 days
-    --
-    + storeToken(userId, accessToken) : void
-    + getToken(userId) : {accessToken}|null
-    + clearToken(userId) : void
-    --
-    Atomic write (.tmp → rename)
-    Pruned on startup + hourly
-  }
-
-  class "SanitizeError" as sanitize <<module>> {
-    + sanitizeError(err) : string
-    --
-    Redacts: query-param secrets,
-    auth headers, bearer tokens,
-    basic-auth URLs
-  }
-
-  class "TagBadge" as tb <<value>> {
-    + label : string
-    + matchedUser : string | null
-  }
-
-  class "ClientInfo" as ci <<value>> {
-    + user : string
-    + type : 'sse'
-    + connectedAt : number (timestamp)
-    + lastSeen : number (timestamp)
-  }
-}
-
-' Relationships
-ep --> appfn : createApp()
-ep --> poller : startPoller()
-
-appfn --> auth : /api/auth (pre-CSRF)
-appfn --> verifycsrf : /api (all routes below)
-appfn --> dashboard
-appfn --> emby_r
-appfn --> sab_r
-appfn --> sonarr_r
-appfn --> radarr_r
-
-dashboard --> requireauth : uses
-emby_r --> requireauth : uses
-sab_r --> requireauth : uses
-sonarr_r --> requireauth : uses
-radarr_r --> requireauth : uses
-
-auth --> tokenstore : storeToken / getToken / clearToken
-
-dashboard --> cache : read/write
-dashboard --> poller : pollAllServices()
-dashboard --> qbt_mod : mapTorrentToDownload()
-dashboard --> config
-
-poller --> cache : set poll:* keys
-poller --> config : get instances
-poller --> qbt_mod : getTorrents()
-
-qbt_mod --> config : getQbittorrentInstances()
-qbt_mod *-- qbt : creates
-qbt --> logger
-
-cache *-- ce : stores
-cache ..> cs : returns from getStats()
-poller ..> pt : stores/returns
-dashboard *-- ci : stores in activeClients
-
-config ..> inst : returns
-
-auth ..> sanitize : sanitizeError on catch
-dashboard ..> sanitize : sanitizeError on catch
-
-@enduml

docs/diagrams/component.puml

@@ -1,118 +0,0 @@
-@startuml component
-!theme plain
-title sofarr — Component Diagram
-
-skinparam componentStyle rectangle
-skinparam packageStyle frame
-
-package "Browser" as browser {
-  [index.html] as html
-  [app.js] as appjs
-  [style.css] as css
-  html ..> appjs : loads
-  html ..> css : loads
-}
-
-package "Express Server" as server {
-
-  [index.js\nEntry Point] as entry
-  [app.js\ncreatApp() factory] as appfactory
-
-  package "Middleware" {
-    [helmet\n(CSP nonce, HSTS)] as hm
-    [express-rate-limit\n(API + login)] as rl
-    [cookie-parser\n(signed cookies)] as cp
-    [express.json\n(64kb limit)] as ej
-    [express.static] as es
-    [requireAuth.js] as requireauth
-    [verifyCsrf.js\n(double-submit)] as verifycsrf
-  }
-
-  package "Routes" as routes {
-    [auth.js\n/api/auth\n(pre-CSRF)] as auth
-    [dashboard.js\n/api/dashboard\n(+SSE /stream)] as dashboard
-    [emby.js\n/api/emby] as emby_route
-    [sabnzbd.js\n/api/sabnzbd] as sab_route
-    [sonarr.js\n/api/sonarr] as sonarr_route
-    [radarr.js\n/api/radarr] as radarr_route
-  }
-
-  package "Utilities" as utils {
-    [poller.js] as poller
-    [cache.js\nMemoryCache] as cache
-    [config.js] as config
-    [qbittorrent.js\nQBittorrentClient] as qbt
-    [tokenStore.js\n(tokens.json)] as tokenstore
-    [sanitizeError.js] as sanitize
-    [logger.js] as logger
-  }
-
-  entry --> appfactory : createApp()
-  entry --> es : serve public/
-  entry --> poller : startPoller()
-
-  appfactory --> hm
-  appfactory --> rl
-  appfactory --> cp
-  appfactory --> ej
-  appfactory --> auth : mount before verifyCsrf
-  appfactory --> verifycsrf : applied to all /api below
-  appfactory --> dashboard
-  appfactory --> emby_route
-  appfactory --> sab_route
-  appfactory --> sonarr_route
-  appfactory --> radarr_route
-
-  emby_route --> requireauth
-  sab_route --> requireauth
-  sonarr_route --> requireauth
-  radarr_route --> requireauth
-  dashboard --> requireauth
-
-  auth --> tokenstore : storeToken / getToken / clearToken
-
-  dashboard --> cache : read poll:* keys
-  dashboard --> poller : pollAllServices()\n(on-demand mode)
-  dashboard --> config : getSonarrInstances()\ngetRadarrInstances()
-  dashboard --> qbt : mapTorrentToDownload()
-
-  poller --> cache : set poll:* keys
-  poller --> config : get all instances
-  poller --> qbt : getTorrents()
-  poller --> logger
-
-  qbt --> config : getQbittorrentInstances()
-  qbt --> logger
-
-  auth ..> sanitize
-  dashboard ..> sanitize
-
-  note "Browser uses EventSource\n(SSE) to /stream.\nServer pushes on each\npoll cycle — no client timer." as sseNote
-  sseNote .. dashboard
-}
-
-cloud "External Services" as external {
-  [Emby / Jellyfin] as emby
-  [SABnzbd] as sab
-  [Sonarr] as sonarr
-  [Radarr] as radarr
-  [qBittorrent] as qbit
-}
-
-auth --> emby : authenticate\nuser profile
-dashboard --> emby : GET /Users\n(user-summary + tag badge classification)
-emby_route --> emby
-sab_route --> sab
-sonarr_route --> sonarr
-radarr_route --> radarr
-
-poller --> sab : queue + history
-poller --> sonarr : tags + queue + history
-poller --> radarr : tags + queue + history
-qbt --> qbit : login + torrents/info
-
-appjs --> auth : POST /login\nGET /me
-appjs --> dashboard : GET /user-downloads\nGET /status
-es --> html : serve static
-
-@enduml

docs/diagrams/seq-auth.puml

@@ -1,104 +0,0 @@
-@startuml seq-auth
-!theme plain
-title sofarr — Authentication Sequence
-
-actor User as user
-participant "Browser\n(app.js)" as browser
-participant "Express\n/api/auth" as auth
-participant "TokenStore\n(tokens.json)" as tokens
-participant "Emby\nServer" as emby
-
-== Page Load ==
-user -> browser : Navigate to sofarr
-activate browser
-browser -> auth : GET /api/auth/me
-activate auth
-auth -> auth : Read emby_user cookie\n(signed if COOKIE_SECRET set)
-alt Cookie exists and valid
-  auth --> browser : { authenticated: true, user: { name, isAdmin } }
-  browser -> auth : GET /api/auth/csrf
-  activate auth
-  auth -> auth : Generate 32-byte hex csrfToken
-  auth --> browser : { csrfToken } + Set csrf_token cookie
-  deactivate auth
-  browser -> browser : store csrfToken in memory
-  browser -> browser : showDashboard()
-  browser -> browser : startAutoRefresh()
-  browser -> browser : dismissSplash()
-else No cookie / tampered
-  auth --> browser : { authenticated: false }
-  browser -> browser : dismissSplash()
-  browser -> browser : showLogin()
-end
-deactivate auth
-
-== Login ==
-user -> browser : Enter username + password\n(+ optional rememberMe checkbox)
-browser -> auth : POST /api/auth/login\n{ username, password, rememberMe }
-activate auth
-note right of auth
-  Rate limiter: max 10 failed
-  attempts per IP / 15 min
-  (successful requests excluded)
-end note
-auth -> emby : POST /Users/authenticatebyname\n{ Username, Pw }\nX-Emby-Authorization: MediaBrowser\nDeviceId = sha256(username)[0:16]
-activate emby
-alt Valid credentials
-  emby --> auth : { User: { Id }, AccessToken }
-  auth -> emby : GET /Users/{userId}\nX-MediaBrowser-Token: AccessToken
-  emby --> auth : { Name, Policy: { IsAdministrator } }
-  deactivate emby
-  auth -> tokens : storeToken(userId, AccessToken)
-  note right of tokens
-    Stored server-side only.
-    Never sent to the client.
-    31-day TTL, atomic JSON write.
-  end note
-  auth -> auth : Set emby_user cookie\n{ id, name, isAdmin }\nhttpOnly, sameSite=strict\nsecure (prod), signed (COOKIE_SECRET)\nrememberMe=true → Max-Age 30d\nrememberMe=false → session cookie
-  auth -> auth : Generate csrfToken\n(32-byte random hex)
-  auth -> auth : Set csrf_token cookie\nhttpOnly=false (JS-readable)\nsameSite=strict, secure (prod)
-  auth --> browser : { success: true, user, csrfToken }
-  browser -> browser : store csrfToken in memory
-  browser -> browser : fadeOutLogin()
-  browser -> browser : showDashboard()
-  browser -> browser : startAutoRefresh()
-  browser -> browser : dismissSplash()
-else Invalid credentials
-  emby --> auth : 401 Error
-  deactivate emby
-  auth --> browser : { success: false, error: "Invalid username or password" }
-  browser -> browser : showLoginError()
-end
-deactivate auth
-
-== CSRF Token Refresh (after page reload) ==
-note over browser : csrfToken lost from memory\non hard page reload
-browser -> auth : GET /api/auth/csrf
-activate auth
-auth -> auth : Generate new csrfToken
-auth --> browser : { csrfToken } + new csrf_token cookie
-deactivate auth
-browser -> browser : store new csrfToken in memory
-
-== Logout ==
-user -> browser : Click Logout
-browser -> browser : stopAutoRefresh()
-browser -> auth : POST /api/auth/logout\n(no CSRF required — auth routes\nexempt; sameSite:strict protects)
-activate auth
-auth -> auth : Parse emby_user cookie → user
-auth -> tokens : getToken(user.id)
-activate tokens
-tokens --> auth : { accessToken }
-deactivate tokens
-auth -> emby : POST /Sessions/Logout\nX-MediaBrowser-Token: accessToken
-activate emby
-emby --> auth : 204 / error (ignored)
-deactivate emby
-auth -> tokens : clearToken(user.id)
-auth -> auth : clearCookie(emby_user)\nclearCookie(csrf_token)
-auth --> browser : { success: true }
-deactivate auth
-browser -> browser : showLogin()
-
-deactivate browser
-@enduml

docs/diagrams/seq-dashboard.puml

@@ -1,67 +0,0 @@
-@startuml seq-dashboard
-!theme plain
-title sofarr — Dashboard SSE Stream Sequence
-
-actor User as user
-participant "Browser\n(app.js)" as browser
-participant "Express\n/api/dashboard" as dashboard
-participant "MemoryCache" as cache
-participant "Poller" as poller
-participant "External\nServices" as ext
-
-== SSE Connection (on login / page load) ==
-user -> browser : Login success\nor valid session
-activate browser
-browser -> dashboard : GET /api/dashboard/stream\n(EventSource, Cookie: emby_user)
-activate dashboard
-
-dashboard -> dashboard : requireAuth: parse cookie\nextract username, isAdmin
-dashboard -> dashboard : Set headers:\nContent-Type: text/event-stream\nX-Accel-Buffering: no
-dashboard -> dashboard : Register in activeClients Map\n{ user, type:'sse', connectedAt }
-
-alt Polling disabled AND cache empty
-  dashboard -> poller : pollAllServices()
-  activate poller
-  poller -> ext : Parallel API calls
-  ext --> poller : Raw data
-  poller -> cache : set poll:* keys (TTL=30s)
-  deactivate poller
-end
-
-== Initial Payload (sent immediately on connect) ==
-dashboard -> cache : get all poll:* keys
-dashboard -> dashboard : Build seriesMap, moviesMap,\nsonarrTagMap, radarrTagMap
-alt showAll=true
-  dashboard -> cache : get('emby:users')
-  alt cache miss
-    dashboard -> ext : GET /Users (Emby)
-    ext --> dashboard : [{ Name, ... }]
-    dashboard -> cache : set('emby:users', map, 60s)
-  end
-end
-dashboard -> dashboard : Match SABnzbd/qBit downloads\nvs Sonarr/Radarr records\nextractUserTag / buildTagBadges
-dashboard --> browser : data: { user, isAdmin, downloads }
-browser -> browser : hideLoading()\nrenderDownloads()
-
-== Pushed Updates (on every poll cycle) ==
-loop Each poll cycle completes
-  poller -> poller : pollAllServices() complete
-  poller -> dashboard : onPollComplete callback fires
-  dashboard -> cache : get all poll:* keys
-  dashboard -> dashboard : Rebuild download payload
-  dashboard --> browser : data: { user, isAdmin, downloads }
-  browser -> browser : renderDownloads() (diff-based)
-end
-
-== Heartbeat (every 25s) ==
-dashboard --> browser : : heartbeat
-note right : Keeps connection alive\nthrough idle-timeout proxies
-
-== Client Disconnects ==
-user -> browser : Close tab / logout
-browser -> dashboard : TCP close (req 'close' event)
-dashboard -> dashboard : offPollComplete(callback)\nclearInterval(heartbeat)\ndelete activeClients[key]
-deactivate dashboard
-deactivate browser
-
-@enduml

docs/diagrams/seq-polling.puml

@@ -1,93 +0,0 @@
-@startuml seq-polling
-!theme plain
-title sofarr — Background Polling Cycle
-
-participant "index.js\n(startup)" as entry
-participant "Poller" as poller
-participant "Config" as config
-participant "SABnzbd\n(per instance)" as sab
-participant "Sonarr\n(per instance)" as sonarr
-participant "Radarr\n(per instance)" as radarr
-participant "qBittorrent\nClient" as qbt
-participant "MemoryCache" as cache
-
-== Startup ==
-entry -> poller : startPoller()
-activate poller
-
-alt POLL_INTERVAL > 0
-  poller -> poller : pollAllServices() (immediate)
-  poller -> poller : setInterval(pollAllServices,\nPOLL_INTERVAL)
-else POLL_INTERVAL = 0
-  poller --> entry : "Polling disabled, on-demand mode"
-end
-
-== Poll Cycle ==
-poller -> poller : Check: polling flag?\n(skip if concurrent)
-poller -> poller : polling = true
-poller -> poller : start = Date.now()
-
-poller -> config : getSABnzbdInstances()
-config --> poller : [{ id, url, apiKey }]
-poller -> config : getSonarrInstances()
-config --> poller : [{ id, url, apiKey }]
-poller -> config : getRadarrInstances()
-config --> poller : [{ id, url, apiKey }]
-
-note over poller : All fetches run in\nparallel via Promise.all,\neach wrapped in timed()
-
-par SABnzbd Queue
-  poller -> sab : GET /api?mode=queue
-  sab --> poller : { queue: { slots, status, speed } }
-and SABnzbd History
-  poller -> sab : GET /api?mode=history&limit=10
-  sab --> poller : { history: { slots } }
-and Sonarr Tags
-  poller -> sonarr : GET /api/v3/tag
-  sonarr --> poller : [{ id, label }]
-and Sonarr Queue
-  poller -> sonarr : GET /api/v3/queue\n?includeSeries=true
-  sonarr --> poller : { records: [{ seriesId, series, ... }] }
-and Sonarr History
-  poller -> sonarr : GET /api/v3/history\n?pageSize=10
-  sonarr --> poller : { records: [{ seriesId, ... }] }
-and Radarr Queue
-  poller -> radarr : GET /api/v3/queue\n?includeMovie=true
-  radarr --> poller : { records: [{ movieId, movie, ... }] }
-and Radarr History
-  poller -> radarr : GET /api/v3/history\n?pageSize=10
-  radarr --> poller : { records: [{ movieId, ... }] }
-and Radarr Tags
-  poller -> radarr : GET /api/v3/tag
-  radarr --> poller : [{ id, label }]
-and qBittorrent
-  poller -> qbt : getTorrents()
-  qbt --> poller : [{ name, progress, ... }]
-end
-
-poller -> poller : Record per-task timings\nlastPollTimings = { totalMs,\ntimestamp, tasks: [{label, ms}] }
-
-poller -> poller : cacheTTL = POLL_INTERVAL × 3
-
-poller -> cache : set('poll:sab-queue', ..., cacheTTL)
-poller -> cache : set('poll:sab-history', ..., cacheTTL)
-poller -> cache : set('poll:sonarr-tags', ..., cacheTTL)
-
-note over poller : Tag queue records with\n_instanceUrl on embedded\nseries/movie objects
-
-poller -> cache : set('poll:sonarr-queue', ..., cacheTTL)
-poller -> cache : set('poll:sonarr-history', ..., cacheTTL)
-poller -> cache : set('poll:radarr-queue', ..., cacheTTL)
-poller -> cache : set('poll:radarr-history', ..., cacheTTL)
-poller -> cache : set('poll:radarr-tags', ..., cacheTTL)
-poller -> cache : set('poll:qbittorrent', ..., cacheTTL)
-
-poller -> poller : Notify SSE subscribers\npollSubscribers.forEach(cb => cb())
-
-note over poller : Each registered SSE client\ncallback rebuilds its payload\nand writes a data: frame
-
-poller -> poller : polling = false\nlog elapsed time
-
-deactivate poller
-
-@enduml

docs/diagrams/state-poller.puml

@@ -1,67 +0,0 @@
-@startuml state-poller
-!theme plain
-title sofarr — Poller State Diagram
-
-[*] --> CheckConfig : startPoller()
-
-state CheckConfig <<choice>>
-CheckConfig --> Disabled : POLL_INTERVAL = 0\nor 'off' / 'false'
-CheckConfig --> Idle : POLL_INTERVAL > 0
-
-state Disabled {
-  state "On-demand mode\nNo background timer" as od
-  od : Data fetched only when\na dashboard request\nfinds empty cache
-}
-
-Disabled --> Polling : pollAllServices()\n(triggered by dashboard request)
-Polling --> Disabled : Poll complete\n(return to on-demand)
-
-state Idle {
-  state "Waiting for\nnext interval" as waiting
-}
-
-Idle --> Polling : setInterval fires\nor immediate first poll
-
-state Polling {
-  state "polling = true" as lock
-  state "Fetching all services\n(Promise.all)" as fetching
-  state "Storing results\nin cache" as storing
-  state "Recording timings" as timing
-
-  [*] --> lock
-  lock --> fetching
-  fetching --> storing : All promises resolved
-  fetching --> ErrorState : Any individual service\nerror (caught per-service)
-  storing --> notifying : Cache updated
-  state "Notifying SSE\nsubscribers" as notifying
-  notifying --> timing
-  timing --> [*] : polling = false
-}
-
-state ErrorState as "Handle Error" {
-  state "Log error\npolling = false" as err
-}
-
-ErrorState --> Idle : Next interval
-Polling --> Idle : Poll complete\n(back to waiting)
-
-state "Concurrent Poll\nAttempt" as skip {
-  state "polling === true\n→ skip" as sk
-}
-
-Idle --> skip : Interval fires while\nprevious still running
-skip --> Idle : Log "still running,\nskipping"
-
-note right of Polling
-  **Cache TTL**: POLL_INTERVAL × 3
-  Ensures data survives between polls
-  even if one cycle is slow.
-end note
-
-note right of Disabled
-  **Cache TTL**: 30000ms (30s)
-  After expiry, next dashboard
-  request triggers a fresh poll.
-end note
-
-@enduml

docs/diagrams/state-ui.puml

@@ -1,73 +0,0 @@
-@startuml state-ui
-!theme plain
-title sofarr — Frontend UI State Diagram
-
-[*] --> SplashScreen : Page load
-
-state SplashScreen {
-  state "Showing splash\n(min 1.2s)" as showing
-}
-
-SplashScreen --> CheckAuth : checkAuthentication()
-
-state CheckAuth <<choice>>
-CheckAuth --> LoginForm : No session cookie
-CheckAuth --> Dashboard : Valid session
-
-state LoginForm {
-  state "Idle" as lf_idle
-  state "Submitting" as lf_submit
-  state "Error" as lf_error
-
-  lf_idle --> lf_submit : Submit form
-  lf_submit --> lf_error : Auth failed
-  lf_error --> lf_submit : Re-submit
-  lf_submit --> FadeOutLogin : Auth success
-}
-
-state FadeOutLogin {
-  state "CSS transition\n(opacity → 0)" as fade
-}
-
-FadeOutLogin --> SplashScreen2 : Show splash\nwhile loading
-
-state SplashScreen2 as "Splash (loading data)" {
-  state "startSSE() — awaiting\nfirst SSE message" as fetching
-}
-
-SplashScreen2 --> Dashboard : Data loaded\ndismissSplash()
-
-state Dashboard {
-  state "Rendering Cards" as rendering
-  state "Status Panel Open" as status_open
-  state "Status Panel Closed" as status_closed
-
-  [*] --> rendering
-  rendering --> rendering : SSE message received
-→ renderDownloads()
-  rendering --> rendering : Theme change
-
-  status_closed --> status_open : Click "Status" btn
-(admin only)
-  status_open --> status_closed : Click close (×)
-  status_open --> status_open : 5s timer
-→ renderStatusPanel()
-
-  [*] --> status_closed
-
-  state "SSE Connection" as sse {
-    state "Connecting" as sc
-    state "Connected" as scon
-    state "Reconnecting" as srec
-    sc --> scon : First message received
-    scon --> srec : Connection lost
-    srec --> scon : Browser auto-reconnects
-    scon --> sc : showAll toggle changed
-  }
-}
-
-Dashboard --> LoginForm : Logout
-(stopSSE,
-clear state)
-
-@enduml

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "sofarr",
-  "version": "0.1.5",
+  "version": "1.3.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sofarr",
-      "version": "0.1.5",
+      "version": "1.3.1",
       "license": "MIT",
       "dependencies": {
         "axios": "^1.6.0",
@@ -14,7 +14,9 @@
         "dotenv": "^16.3.1",
         "express": "^4.18.2",
         "express-rate-limit": "^7.0.0",
-        "helmet": "^7.0.0"
+        "helmet": "^7.0.0",
+        "jsdom": "^29.1.1",
+        "xmlrpc": "^1.3.2"
       },
       "devDependencies": {
         "@vitest/coverage-v8": "^4.1.6",
@@ -25,6 +27,53 @@
         "vitest": "^4.1.6"
       }
     },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "5.1.11",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.1.11.tgz",
+      "integrity": "sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==",
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@csstools/css-calc": "^3.2.0",
+        "@csstools/css-color-parser": "^4.1.0",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/dom-selector": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-7.1.1.tgz",
+      "integrity": "sha512-67RZDnYRc8H/8MLDgQCDE//zoqVFwajkepHZgmXrbwybzXOEwOWGPYGmALYl9J2DOLfFPPs6kKCqmbzV895hTQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@asamuzakjp/nwsapi": "^2.3.9",
+        "bidi-js": "^1.0.3",
+        "css-tree": "^3.2.1",
+        "is-potential-custom-element-name": "^1.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/generational-cache": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/generational-cache/-/generational-cache-1.0.1.tgz",
+      "integrity": "sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg==",
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/nwsapi": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/nwsapi/-/nwsapi-2.3.9.tgz",
+      "integrity": "sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==",
+      "license": "MIT"
+    },
     "node_modules/@babel/helper-string-parser": {
       "version": "7.27.1",
       "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
@@ -95,6 +144,152 @@
         "node": ">=18"
       }
     },
+    "node_modules/@bramus/specificity": {
+      "version": "2.4.2",
+      "resolved": "https://registry.npmjs.org/@bramus/specificity/-/specificity-2.4.2.tgz",
+      "integrity": "sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==",
+      "license": "MIT",
+      "dependencies": {
+        "css-tree": "^3.0.0"
+      },
+      "bin": {
+        "specificity": "bin/cli.js"
+      }
+    },
+    "node_modules/@csstools/color-helpers": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.0.2.tgz",
+      "integrity": "sha512-LMGQLS9EuADloEFkcTBR3BwV/CGHV7zyDxVRtVDTwdI2Ca4it0CCVTT9wCkxSgokjE5Ho41hEPgb8OEUwoXr6Q==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.2.1.tgz",
+      "integrity": "sha512-DtdHlgXh5ZkA43cwBcAm+huzgJiwx3ZTWVjBs94kwz2xKqSimDA3lBgCjphYgwgVUMWatSM0pDd8TILB1yrVVg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.1.1.tgz",
+      "integrity": "sha512-eZ5XOtyhK+mggRafYUWzA0tvaYOFgdY8AkgQiCJF9qNAePnUo/zmsqqYubBBb3sQ8uNUaSKTY9s9klfRaAXL0g==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^6.0.2",
+        "@csstools/css-calc": "^3.2.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-4.0.0.tgz",
+      "integrity": "sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-syntax-patches-for-csstree": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.4.tgz",
+      "integrity": "sha512-wgsqt92b7C7tQhIdPNxj0n9zuUbQlvAuI1exyzeNrOKOi62SD7ren8zqszmpVREjAOqg8cD2FqYhQfAuKjk4sw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "peerDependencies": {
+        "css-tree": "^3.2.1"
+      },
+      "peerDependenciesMeta": {
+        "css-tree": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-4.0.0.tgz",
+      "integrity": "sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
     "node_modules/@emnapi/core": {
       "version": "1.10.0",
       "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
@@ -129,6 +324,23 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@exodus/bytes": {
+      "version": "1.15.0",
+      "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.15.0.tgz",
+      "integrity": "sha512-UY0nlA+feH81UGSHv92sLEPLCeZFjXOuHhrIo0HQydScuQc8s0A7kL/UdgwgDq8g8ilksmuoF35YVTNphV2aBQ==",
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "@noble/hashes": "^1.8.0 || ^2.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@noble/hashes": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@jridgewell/resolve-uri": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
@@ -198,7 +410,7 @@
       "version": "1.8.0",
       "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
       "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": "^14.21.3 || >=16"
@@ -854,6 +1066,15 @@
         "node": "18 || 20 || >=22"
       }
     },
+    "node_modules/bidi-js": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
+      "integrity": "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==",
+      "license": "MIT",
+      "dependencies": {
+        "require-from-string": "^2.0.2"
+      }
+    },
     "node_modules/binary-extensions": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz",
@@ -1168,6 +1389,32 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/css-tree": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz",
+      "integrity": "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==",
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.27.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0"
+      }
+    },
+    "node_modules/data-urls": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-7.0.0.tgz",
+      "integrity": "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==",
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/date-fns": {
       "version": "2.30.0",
       "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-2.30.0.tgz",
@@ -1194,6 +1441,12 @@
         "ms": "2.0.0"
       }
     },
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "license": "MIT"
+    },
     "node_modules/delayed-stream": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
@@ -1291,6 +1544,18 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/entities": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-8.0.0.tgz",
+      "integrity": "sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/es-define-property": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@@ -1713,6 +1978,18 @@
         "node": ">=16.0.0"
       }
     },
+    "node_modules/html-encoding-sniffer": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-6.0.0.tgz",
+      "integrity": "sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==",
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.6.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/html-escaper": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
@@ -1873,6 +2150,12 @@
         "node": ">=0.12.0"
       }
     },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "license": "MIT"
+    },
     "node_modules/istanbul-lib-coverage": {
       "version": "3.2.2",
       "resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
@@ -1932,6 +2215,46 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/jsdom": {
+      "version": "29.1.1",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-29.1.1.tgz",
+      "integrity": "sha512-ECi4Fi2f7BdJtUKTflYRTiaMxIB0O6zfR1fX0GXpUrf6flp8QIYn1UT20YQqdSOfk2dfkCwS8LAFoJDEppNK5Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/css-color": "^5.1.11",
+        "@asamuzakjp/dom-selector": "^7.1.1",
+        "@bramus/specificity": "^2.4.2",
+        "@csstools/css-syntax-patches-for-csstree": "^1.1.3",
+        "@exodus/bytes": "^1.15.0",
+        "css-tree": "^3.2.1",
+        "data-urls": "^7.0.0",
+        "decimal.js": "^10.6.0",
+        "html-encoding-sniffer": "^6.0.0",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.3.5",
+        "parse5": "^8.0.1",
+        "saxes": "^6.0.0",
+        "symbol-tree": "^3.2.4",
+        "tough-cookie": "^6.0.1",
+        "undici": "^7.25.0",
+        "w3c-xmlserializer": "^5.0.0",
+        "webidl-conversions": "^8.0.1",
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.1",
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "canvas": "^3.0.0"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/json-stringify-safe": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/json-stringify-safe/-/json-stringify-safe-5.0.1.tgz",
@@ -2207,6 +2530,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/lru-cache": {
+      "version": "11.3.6",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.6.tgz",
+      "integrity": "sha512-Gf/KoL3C/MlI7Bt0PGI9I+TeTC/I6r/csU58N4BSNc4lppLBeKsOdFYkK+dX0ABDUMJNfCHTyPpzwwO21Awd3A==",
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.30.21",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
@@ -2254,6 +2586,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/mdn-data": {
+      "version": "2.27.1",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz",
+      "integrity": "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==",
+      "license": "CC0-1.0"
+    },
     "node_modules/media-typer": {
       "version": "0.3.0",
       "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz",
@@ -2518,6 +2856,18 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/parse5": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz",
+      "integrity": "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==",
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^8.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
     "node_modules/parseurl": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
@@ -2628,6 +2978,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/qs": {
       "version": "6.15.2",
       "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz",
@@ -2690,6 +3049,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/rolldown": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.1.tgz",
@@ -2760,6 +3128,24 @@
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
       "license": "MIT"
     },
+    "node_modules/sax": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/sax/-/sax-1.2.4.tgz",
+      "integrity": "sha512-NqVDv9TpANUjFm0N8uM5GxL36UgKi9/atZw+x7YFnQ8ckwFGKrl4xX4yWtrey3UJm5nP1kUbnYgLopqWNSRhWw==",
+      "license": "ISC"
+    },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "license": "ISC",
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
     "node_modules/semver": {
       "version": "7.8.0",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
@@ -2933,7 +3319,6 @@
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
       "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
-      "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">=0.10.0"
@@ -3103,6 +3488,12 @@
         "url": "https://github.com/chalk/supports-color?sponsor=1"
       }
     },
+    "node_modules/symbol-tree": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
+      "license": "MIT"
+    },
     "node_modules/tinybench": {
       "version": "2.9.0",
       "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
@@ -3178,6 +3569,24 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/tldts": {
+      "version": "7.0.30",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.0.30.tgz",
+      "integrity": "sha512-ELrFxuqsDdHUwoh0XxDbxuLD3Wnz49Z57IFvTtvWy1hJdcMZjXLIuonjilCiWHlT2GbE4Wlv1wKVTzDFnXH1aw==",
+      "license": "MIT",
+      "dependencies": {
+        "tldts-core": "^7.0.30"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "7.0.30",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.0.30.tgz",
+      "integrity": "sha512-uiHN8PIB1VmWyS98eZYja4xzlYqeFZVjb4OuYlJQnZAuJhMw4PbKQOKgHKhBdJR3FE/t5mUQ1Kd80++B+qhD1Q==",
+      "license": "MIT"
+    },
     "node_modules/to-regex-range": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
@@ -3210,6 +3619,30 @@
         "nodetouch": "bin/nodetouch.js"
       }
     },
+    "node_modules/tough-cookie": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.1.tgz",
+      "integrity": "sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "tldts": "^7.0.5"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
+      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
+      "license": "MIT",
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/tree-kill": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz",
@@ -3247,6 +3680,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/undici": {
+      "version": "7.25.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.25.0.tgz",
+      "integrity": "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.18.1"
+      }
+    },
     "node_modules/unpipe": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
@@ -3468,6 +3910,50 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/w3c-xmlserializer": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
+      "license": "MIT",
+      "dependencies": {
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/webidl-conversions": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
+      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
+      "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-url": {
+      "version": "16.0.1",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz",
+      "integrity": "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==",
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.11.0",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/why-is-node-running": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
@@ -3510,6 +3996,44 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/xml-name-validator": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/xmlbuilder": {
+      "version": "8.2.2",
+      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-8.2.2.tgz",
+      "integrity": "sha512-eKRAFz04jghooy8muekqzo8uCSVNeyRedbuJrp0fovbLIi7wlsYtdUn3vBAAPq2Y3/0xMz2WMEUQ8yhVVO9Stw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "license": "MIT"
+    },
+    "node_modules/xmlrpc": {
+      "version": "1.3.2",
+      "resolved": "https://registry.npmjs.org/xmlrpc/-/xmlrpc-1.3.2.tgz",
+      "integrity": "sha512-jQf5gbrP6wvzN71fgkcPPkF4bF/Wyovd7Xdff8d6/ihxYmgETQYSuTc+Hl+tsh/jmgPLro/Aro48LMFlIyEKKQ==",
+      "license": "MIT",
+      "dependencies": {
+        "sax": "1.2.x",
+        "xmlbuilder": "8.2.x"
+      },
+      "engines": {
+        "node": ">=0.8",
+        "npm": ">=1.0.0"
+      }
+    },
     "node_modules/y18n": {
       "version": "5.0.8",
       "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sofarr",
-  "version": "1.0.0",
+  "version": "1.4.0",
   "description": "A personal media download dashboard that shows your downloads 'so far' while you relax on the sofa waiting for your *arr services to finish",
   "main": "server/index.js",
   "scripts": {
@@ -21,7 +21,9 @@
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
     "express-rate-limit": "^7.0.0",
-    "helmet": "^7.0.0"
+    "helmet": "^7.0.0",
+    "jsdom": "^29.1.1",
+    "xmlrpc": "^1.3.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.6",

public/.well-known/security.txt

@@ -0,0 +1,5 @@
+Contact: mailto:gordon@i3omb.com
+Expires: 2026-12-31T23:59:00.000Z
+Preferred-Languages: en
+Canonical: https://git.i3omb.com/Gandalf/sofarr
+Policy: https://git.i3omb.com/Gandalf/sofarr/src/branch/main/SECURITY.md

public/app.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 let currentUser = null;
 let downloads = [];
 let isAdmin = false;
@@ -5,6 +6,13 @@ let showAll = false;
 let csrfToken = null; // double-submit CSRF token, sent as X-CSRF-Token on mutating requests
 const SPLASH_MIN_MS = 1200; // minimum splash display time
 
+// History section state
+let historyDays = parseInt(localStorage.getItem('sofarr-history-days'), 10) || 7;
+let historyRefreshHandle = null;
+const HISTORY_REFRESH_MS = 5 * 60 * 1000; // auto-refresh history every 5 min
+let ignoreAvailable = localStorage.getItem('sofarr-ignore-available') === 'true';
+let lastHistoryItems = []; // raw items from last fetch, for re-filtering without a network round-trip
+
 // SSE stream state
 let sseSource = null;
 let sseReconnectTimer = null;
@@ -20,13 +28,28 @@ const SSE_RECONNECT_MS = 3000; // browser already retries, but we add explicit b
 document.addEventListener('DOMContentLoaded', () => {
   checkAuthentication();
   initThemeSwitcher();
-  
+  initTabs();
+  initHistoryControls();
+  loadAppVersion();
+
   document.getElementById('login-form').addEventListener('submit', handleLogin);
   document.getElementById('logout-btn').addEventListener('click', handleLogout);
   document.getElementById('show-all-toggle').addEventListener('change', handleShowAllToggle);
   document.getElementById('status-btn').addEventListener('click', toggleStatusPanel);
+  document.getElementById('title-home-link').addEventListener('click', e => { e.preventDefault(); goHome(); });
 });
 
+function loadAppVersion() {
+  fetch('/health')
+    .then(r => r.json())
+    .then(data => {
+      if (data.version) {
+        document.getElementById('app-version').textContent = `sofarr v${data.version}`;
+      }
+    })
+    .catch(() => {});
+}
+
 function initThemeSwitcher() {
   const saved = localStorage.getItem('sofarr-theme') || 'light';
   document.querySelectorAll('.theme-btn').forEach(btn => {
@@ -43,6 +66,42 @@ function setTheme(theme) {
   });
 }
 
+function goHome() {
+  closeStatusPanel();
+  // Reset showAll if active
+  if (showAll) {
+    showAll = false;
+    const toggle = document.getElementById('show-all-toggle');
+    if (toggle) toggle.checked = false;
+    startSSE();
+  }
+  activateTab('downloads', true);
+}
+
+function initTabs() {
+  const savedTab = localStorage.getItem('sofarr-active-tab') || 'downloads';
+  activateTab(savedTab, false);
+
+  document.querySelectorAll('.tab-btn').forEach(btn => {
+    btn.addEventListener('click', () => {
+      const tab = btn.dataset.tab;
+      activateTab(tab, true);
+    });
+  });
+}
+
+function activateTab(tabName, save) {
+  document.querySelectorAll('.tab-btn').forEach(btn => {
+    btn.classList.toggle('active', btn.dataset.tab === tabName);
+  });
+  document.querySelectorAll('.tab-panel').forEach(panel => {
+    panel.style.display = panel.id === `tab-${tabName}` ? '' : 'none';
+  });
+  if (save) localStorage.setItem('sofarr-active-tab', tabName);
+  // Load history the first time the history tab is shown
+  if (tabName === 'history') loadHistory();
+}
+
 // --- SSE connection management ---
 
 function startSSE() {
@@ -88,6 +147,8 @@ function handleShowAllToggle(e) {
   showAll = e.target.checked;
   // Re-open stream with updated showAll param
   startSSE();
+  // Reload history with updated showAll param
+  loadHistory();
 }
 
 function fadeOutLogin() {
@@ -209,6 +270,7 @@ async function handleLogin(e) {
 async function handleLogout() {
   try {
     stopSSE();
+    stopHistoryRefresh();
     if (statusRefreshHandle) { clearInterval(statusRefreshHandle); statusRefreshHandle = null; }
     await fetch('/api/auth/logout', {
       method: 'POST',
@@ -217,6 +279,7 @@ async function handleLogout() {
     currentUser = null;
     csrfToken = null;
     downloads = [];
+    clearHistory();
     showLogin();
   } catch (err) {
     console.error('Logout failed:', err);
@@ -238,6 +301,10 @@ function showDashboard() {
   sp.style.display = 'none';
   sp.innerHTML = '';
   document.getElementById('admin-controls').style.display = isAdmin ? 'flex' : 'none';
+  // Initialise days input from saved value
+  const daysInput = document.getElementById('history-days');
+  if (daysInput) daysInput.value = historyDays;
+  startHistoryRefresh();
 }
 
 function showLoginError(message) {
@@ -251,6 +318,30 @@ function hideLoginError() {
   errorDiv.style.display = 'none';
 }
 
+// Build an episode-info element for series downloads/history.
+// Single episode: "S01E05 — Episode Title"
+// Multiple episodes: "Multiple episodes" with tooltip listing them all.
+// Returns null if no episode data.
+function formatEpisodeInfo(episodes) {
+  if (!episodes || episodes.length === 0) return null;
+  const el = document.createElement('p');
+  el.className = 'episode-info';
+  if (episodes.length === 1) {
+    const ep = episodes[0];
+    const code = 'S' + String(ep.season).padStart(2, '0') + 'E' + String(ep.episode).padStart(2, '0');
+    el.textContent = ep.title ? code + ' \u2014 ' + ep.title : code;
+  } else {
+    el.textContent = 'Multiple episodes';
+    el.classList.add('multi-episode');
+    const lines = episodes.map(ep => {
+      const code = 'S' + String(ep.season).padStart(2, '0') + 'E' + String(ep.episode).padStart(2, '0');
+      return ep.title ? code + ' \u2014 ' + ep.title : code;
+    });
+    el.setAttribute('data-tooltip', lines.join('\n'));
+  }
+  return el;
+}
+
 // fetchUserDownloads is kept for the showAll toggle re-connection case
 // but the primary data path is now via SSE (startSSE / EventSource).
 
@@ -359,13 +450,57 @@ function updateDownloadCard(card, download) {
       peersEl.textContent = download.peers;
     }
     
-    const availabilityEl = card.querySelector('.detail-item[data-label="Availability"] .detail-value');
-    if (availabilityEl && download.availability !== undefined) {
-      availabilityEl.textContent = `${download.availability}%`;
+    const availabilityItem = card.querySelector('.detail-item[data-label="Availability"]');
+    if (availabilityItem && download.availability !== undefined) {
+      availabilityItem.querySelector('.detail-value').textContent = `${download.availability}%`;
+      availabilityItem.classList.toggle('availability-warning', parseFloat(download.availability) < 100);
     }
   }
 }
 
+async function handleBlocklistSearch(btn, download) {
+  if (!confirm(`Blocklist "${download.title}" and trigger a new search?\n\nThis will:\n• Remove the download from the download client\n• Add this release to the blocklist\n• Trigger an automatic search for a new release`)) return;
+
+  btn.disabled = true;
+  btn.textContent = '⏳ Working…';
+
+  try {
+    const res = await fetch('/api/dashboard/blocklist-search', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': csrfToken
+      },
+      body: JSON.stringify({
+        arrQueueId: download.arrQueueId,
+        arrType: download.arrType,
+        arrInstanceUrl: download.arrInstanceUrl,
+        arrInstanceKey: download.arrInstanceKey,
+        arrContentId: download.arrContentId,
+        arrContentType: download.arrContentType
+      })
+    });
+
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({}));
+      throw new Error(data.error || `HTTP ${res.status}`);
+    }
+
+    btn.textContent = '✓ Done — searching…';
+    btn.className = 'blocklist-search-btn success';
+  } catch (err) {
+    console.error('[Blocklist] Error:', err);
+    btn.disabled = false;
+    btn.textContent = '⛔ Blocklist & Search';
+    btn.className = 'blocklist-search-btn error';
+    btn.title = `Failed: ${err.message}`;
+    setTimeout(() => {
+      btn.className = 'blocklist-search-btn';
+      btn.title = 'Remove this release from the download client, add it to the blocklist, and trigger a new automatic search';
+    }, 4000);
+  }
+}
+
 function createDownloadCard(download) {
   const card = document.createElement('div');
   card.className = `download-card ${download.type}`;
@@ -421,6 +556,15 @@ function createDownloadCard(download) {
     issueBadge.setAttribute('data-tooltip', download.importIssues.join('\n'));
     header.appendChild(issueBadge);
   }
+
+  if ((isAdmin || download.canBlocklist) && download.arrQueueId) {
+    const blBtn = document.createElement('button');
+    blBtn.className = 'blocklist-search-btn';
+    blBtn.textContent = '⛔ Blocklist & Search';
+    blBtn.title = 'Remove this release from the download client, add it to the blocklist, and trigger a new automatic search';
+    blBtn.addEventListener('click', () => handleBlocklistSearch(blBtn, download));
+    header.appendChild(blBtn);
+  }
   
   const title = document.createElement('h3');
   title.className = 'download-title';
@@ -438,6 +582,8 @@ function createDownloadCard(download) {
       series.textContent = `Series: ${download.seriesName}`;
     }
     infoDiv.appendChild(series);
+    const epEl = formatEpisodeInfo(download.episodes);
+    if (epEl) infoDiv.appendChild(epEl);
   }
   
   if (download.movieName) {
@@ -558,6 +704,7 @@ function createDownloadCard(download) {
     
     if (download.availability !== undefined) {
       const availability = createDetailItem('Availability', `${download.availability}%`);
+      if (parseFloat(download.availability) < 100) availability.classList.add('availability-warning');
       details.appendChild(availability);
     }
   }
@@ -782,3 +929,221 @@ function hideLoading() {
   const loading = document.getElementById('loading');
   loading.style.display = 'none';
 }
+
+// =============================================================================
+// History section
+// =============================================================================
+
+function initHistoryControls() {
+  const daysInput = document.getElementById('history-days');
+  const refreshBtn = document.getElementById('history-refresh-btn');
+  const ignoreToggle = document.getElementById('ignore-available-toggle');
+  if (daysInput) {
+    daysInput.addEventListener('change', () => {
+      const v = parseInt(daysInput.value, 10);
+      if (v > 0 && v <= 90) {
+        historyDays = v;
+        localStorage.setItem('sofarr-history-days', v);
+        loadHistory();
+      }
+    });
+  }
+  if (refreshBtn) {
+    refreshBtn.addEventListener('click', () => loadHistory(true));
+  }
+  if (ignoreToggle) {
+    ignoreToggle.checked = ignoreAvailable;
+    ignoreToggle.addEventListener('change', () => {
+      ignoreAvailable = ignoreToggle.checked;
+      localStorage.setItem('sofarr-ignore-available', ignoreAvailable);
+      renderHistory(lastHistoryItems);
+    });
+  }
+}
+
+function startHistoryRefresh() {
+  stopHistoryRefresh();
+  historyRefreshHandle = setInterval(() => loadHistory(), HISTORY_REFRESH_MS);
+}
+
+function stopHistoryRefresh() {
+  if (historyRefreshHandle) {
+    clearInterval(historyRefreshHandle);
+    historyRefreshHandle = null;
+  }
+}
+
+function clearHistory() {
+  lastHistoryItems = [];
+  document.getElementById('history-list').innerHTML = '';
+  document.getElementById('no-history').style.display = 'none';
+  document.getElementById('history-error').style.display = 'none';
+}
+
+async function loadHistory(forceRefresh = false) {
+  const listEl = document.getElementById('history-list');
+  const loadingEl = document.getElementById('history-loading');
+  const errorEl = document.getElementById('history-error');
+  const noHistoryEl = document.getElementById('no-history');
+
+  loadingEl.style.display = 'block';
+  errorEl.style.display = 'none';
+  noHistoryEl.style.display = 'none';
+
+  try {
+    const params = new URLSearchParams({ days: historyDays });
+    if (showAll) params.set('showAll', 'true');
+    if (forceRefresh) params.set('_t', Date.now());
+    const res = await fetch(`/api/history/recent?${params}`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json();
+    loadingEl.style.display = 'none';
+    lastHistoryItems = data.history || [];
+    renderHistory(lastHistoryItems);
+  } catch (err) {
+    loadingEl.style.display = 'none';
+    errorEl.textContent = 'Failed to load history.';
+    errorEl.style.display = 'block';
+    console.error('[History] Load error:', err);
+  }
+}
+
+function renderHistory(items) {
+  const listEl = document.getElementById('history-list');
+  const noHistoryEl = document.getElementById('no-history');
+  listEl.innerHTML = '';
+  const visible = ignoreAvailable
+    ? items.filter(item => !(item.outcome === 'failed' && item.availableForUpgrade))
+    : items;
+  if (!visible.length) {
+    noHistoryEl.style.display = 'block';
+    return;
+  }
+  noHistoryEl.style.display = 'none';
+  visible.forEach(item => listEl.appendChild(createHistoryCard(item)));
+}
+
+function createHistoryCard(item) {
+  const card = document.createElement('div');
+  card.className = `history-card ${item.type} ${item.outcome}`;
+
+  if (item.coverArt) {
+    const coverDiv = document.createElement('div');
+    coverDiv.className = 'history-cover';
+    const img = document.createElement('img');
+    img.src = '/api/dashboard/cover-art?url=' + encodeURIComponent(item.coverArt);
+    img.alt = item.movieName || item.seriesName || item.title;
+    img.loading = 'lazy';
+    coverDiv.appendChild(img);
+    card.appendChild(coverDiv);
+  }
+
+  const info = document.createElement('div');
+  info.className = 'history-info';
+
+  // Header row: type badge + outcome badge
+  const header = document.createElement('div');
+  header.className = 'history-card-header';
+
+  const typeBadge = document.createElement('span');
+  typeBadge.className = `history-type-badge ${item.type}`;
+  typeBadge.textContent = item.type === 'series' ? '📺 Series' : '🎬 Movie';
+  header.appendChild(typeBadge);
+
+  const outcomeBadge = document.createElement('span');
+  outcomeBadge.className = `history-outcome-badge ${item.outcome}`;
+  outcomeBadge.textContent = item.outcome === 'imported' ? '✓ Imported' : '✗ Failed';
+  header.appendChild(outcomeBadge);
+
+  if (item.availableForUpgrade) {
+    const upgradeBadge = document.createElement('span');
+    upgradeBadge.className = 'history-upgrade-badge';
+    upgradeBadge.title = 'A previous version of this item is available. An upgrade download has failed.';
+    upgradeBadge.textContent = '⬆ Available';
+    header.appendChild(upgradeBadge);
+  }
+
+  if (item.instanceName) {
+    const instBadge = document.createElement('span');
+    instBadge.className = 'history-instance-badge';
+    instBadge.textContent = item.instanceName;
+    header.appendChild(instBadge);
+  }
+
+  if (showAll && item.tagBadges && item.tagBadges.length > 0) {
+    const unmatched = item.tagBadges.filter(b => !b.matchedUser);
+    const matched = item.tagBadges.filter(b => b.matchedUser);
+    for (const b of unmatched) {
+      const badge = document.createElement('span');
+      badge.className = 'download-user-badge unmatched';
+      badge.textContent = b.label;
+      header.appendChild(badge);
+    }
+    for (const b of matched) {
+      const badge = document.createElement('span');
+      badge.className = 'download-user-badge';
+      badge.textContent = b.matchedUser;
+      header.appendChild(badge);
+    }
+  } else if (item.matchedUserTag) {
+    const badge = document.createElement('span');
+    badge.className = 'download-user-badge';
+    badge.textContent = item.matchedUserTag;
+    header.appendChild(badge);
+  }
+
+  info.appendChild(header);
+
+  // Title
+  const title = document.createElement('h3');
+  title.className = 'history-title';
+  title.textContent = item.title;
+  info.appendChild(title);
+
+  // Series/movie name with optional arr link
+  if (item.seriesName) {
+    const p = document.createElement('p');
+    p.className = 'history-media-name';
+    if (isAdmin && item.arrLink) {
+      p.innerHTML = 'Series: <a href="' + escapeHtml(item.arrLink) + '" target="_blank" class="arr-link">' + escapeHtml(item.seriesName) + '</a>';
+    } else {
+      p.textContent = 'Series: ' + item.seriesName;
+    }
+    info.appendChild(p);
+    const epEl = formatEpisodeInfo(item.episodes);
+    if (epEl) info.appendChild(epEl);
+  }
+  if (item.movieName) {
+    const p = document.createElement('p');
+    p.className = 'history-media-name';
+    if (isAdmin && item.arrLink) {
+      p.innerHTML = 'Movie: <a href="' + escapeHtml(item.arrLink) + '" target="_blank" class="arr-link">' + escapeHtml(item.movieName) + '</a>';
+    } else {
+      p.textContent = 'Movie: ' + item.movieName;
+    }
+    info.appendChild(p);
+  }
+
+  // Detail pills
+  const details = document.createElement('div');
+  details.className = 'history-details';
+
+  if (item.completedAt) {
+    details.appendChild(createDetailItem('Completed', formatDate(item.completedAt)));
+  }
+  if (item.quality) {
+    details.appendChild(createDetailItem('Quality', item.quality));
+  }
+
+  // Failed imports: show failure message
+  if (item.outcome === 'failed' && item.failureMessage) {
+    const failItem = document.createElement('div');
+    failItem.className = 'history-failure-message';
+    failItem.textContent = item.failureMessage;
+    details.appendChild(failItem);
+  }
+
+  info.appendChild(details);
+  card.appendChild(info);
+  return card;
+}

public/index.html

@@ -46,7 +46,7 @@
         <!-- Dashboard -->
         <div id="dashboard-container" class="dashboard-container" style="display: none;">
             <header class="app-header">
-                <h1>sofarr</h1>
+                <h1><a href="#" class="title-link" id="title-home-link"><img src="favicon-192.png" alt="" class="title-logo">sofarr</a></h1>
                 <div class="header-controls">
                     <div class="theme-switcher">
                         <button class="theme-btn active" data-theme="light">Light</button>
@@ -74,17 +74,49 @@
 
             <div id="loading" class="loading" style="display: none;">Loading downloads...</div>
 
-            <div class="downloads-container">
-                <h2>Your Downloads</h2>
-                <div id="no-downloads" class="no-downloads" style="display: none;">
-                    <p>No downloads found for your user.</p>
-                    <p>Make sure your shows and movies are tagged with your username in Sonarr/Radarr.</p>
+            <div class="main-tabs">
+                <div class="tab-bar">
+                    <button class="tab-btn active" data-tab="downloads">Active Downloads</button>
+                    <button class="tab-btn" data-tab="history">Recently Completed</button>
+                </div>
+
+                <div class="tab-panel" id="tab-downloads">
+                    <div class="downloads-container">
+                        <div id="no-downloads" class="no-downloads" style="display: none;">
+                            <p>No downloads found for your user.</p>
+                            <p>Make sure your shows and movies are tagged with your username in Sonarr/Radarr.</p>
+                        </div>
+                        <div id="downloads-list" class="downloads-list"></div>
+                    </div>
+                </div>
+
+                <div class="tab-panel" id="tab-history" style="display: none;">
+                    <div class="history-container" id="history-container">
+                        <div class="history-header">
+                            <div class="history-controls">
+                                <label class="history-days-label" for="history-days">Last</label>
+                                <input type="number" id="history-days" class="history-days-input" value="7" min="1" max="90">
+                                <span class="history-days-label">days</span>
+                                <button id="history-refresh-btn" class="history-refresh-btn" title="Refresh history">&#8635;</button>
+                                <label class="history-toggle-label" id="ignore-available-label" data-tooltip="Hide failed downloads where the item is already available on disk (i.e. a failed upgrade attempt)">
+                                    <input type="checkbox" id="ignore-available-toggle">
+                                    <span>Hide upgrade failures</span>
+                                </label>
+                            </div>
+                        </div>
+                        <div id="history-loading" class="history-loading" style="display: none;">Loading history...</div>
+                        <div id="history-error" class="history-error" style="display: none;"></div>
+                        <div id="no-history" class="no-history" style="display: none;">
+                            <p>No completed downloads found in this period.</p>
+                        </div>
+                        <div id="history-list" class="history-list"></div>
+                    </div>
                 </div>
-                <div id="downloads-list" class="downloads-list"></div>
             </div>
 
             <footer class="app-footer">
                 <p>Ensure your media is tagged with your username in Sonarr/Radarr to match downloads to users.</p>
+                <a href="https://git.i3omb.com/Gandalf/sofarr" target="_blank" rel="noopener noreferrer" class="app-version" id="app-version"></a>
             </footer>
         </div>
     </div>

public/style.css

@@ -31,41 +31,68 @@
 
 /* ===== Theme Variables ===== */
 :root, [data-theme="light"] {
-  --bg-gradient-start: #667eea;
-  --bg-gradient-end: #764ba2;
+  /* Page background — clean off-white matching logo backdrop */
+  --bg-gradient-start: #e8eef3;
+  --bg-gradient-end: #d4dee8;
+
+  /* Surfaces */
   --surface: #ffffff;
-  --surface-alt: #f5f5f5;
-  --text-primary: #333333;
-  --text-secondary: #666666;
-  --text-muted: #999999;
-  --border: #e0e0e0;
-  --accent: #667eea;
-  --accent-hover: #5568d3;
-  --accent-light: #e8eaf6;
-  --series-color: #667eea;
-  --series-bg: #e8eaf6;
-  --movie-color: #e040a0;
-  --movie-bg: #fce4ec;
-  --torrent-color: #26a69a;
-  --torrent-bg: #e0f2f1;
-  --success: #4caf50;
+  --surface-alt: #f0f4f7;
+
+  /* Typography — charcoal from logo, all meet WCAG AA on white */
+  --text-primary: #2b2f33;   /* ~14:1 on white */
+  --text-secondary: #4d5760; /* ~7.5:1 on white */
+  --text-muted: #6b7784;     /* ~4.6:1 on white — AA compliant */
+
+  /* Borders */
+  --border: #c8d3db;
+
+  /* Accent — primary teal from couch outline */
+  --accent: #1f7d94;         /* ~4.6:1 on white — AA compliant */
+  --accent-hover: #165f70;   /* darker for hover */
+  --accent-light: #e0f0f4;   /* very light teal tint for backgrounds */
+
+  /* Series — steel blue from sofa body */
+  --series-color: #1e6b8a;   /* ~5.0:1 on white — AA */
+  --series-bg: #dceef5;
+
+  /* Movie — warm coral (complementary to teal, accessible) */
+  --movie-color: #b5451b;    /* ~5.5:1 on white — AA */
+  --movie-bg: #fdeee8;
+
+  /* Torrent — mid teal-green */
+  --torrent-color: #1a7a6e;  /* ~4.7:1 on white — AA */
+  --torrent-bg: #ddf2ef;
+
+  /* State colours */
+  --success: #2e7d32;        /* ~7.1:1 on white — AA */
   --success-bg: #e8f5e9;
-  --info: #2196f3;
-  --info-bg: #e3f2fd;
-  --danger: #f44336;
-  --danger-bg: #ffebee;
-  --danger-border: #ffcdd2;
-  --progress-bg: #ffebee;
-  --progress-border: #ffcdd2;
-  --progress-fill-start: #4caf50;
-  --progress-fill-end: #66bb6a;
-  --shadow: rgba(0, 0, 0, 0.1);
-  --shadow-strong: rgba(0, 0, 0, 0.15);
-  --footer-text: rgba(255, 255, 255, 0.9);
+  --info: #1565c0;           /* ~7.3:1 on white — AA */
+  --info-bg: #e3f0fb;
+  --danger: #c62828;         /* ~6.5:1 on white — AA */
+  --danger-bg: #fdecea;
+  --danger-border: #f5c6c2;
+
+  /* Progress bar */
+  --progress-bg: #eaf2f5;
+  --progress-border: #c8d3db;
+  --progress-fill-start: #1f7d94;
+  --progress-fill-end: #2da0bc;
+
+  /* Shadows */
+  --shadow: rgba(30, 60, 80, 0.10);
+  --shadow-strong: rgba(30, 60, 80, 0.18);
+
+  /* Footer — dark text on light page background */
+  --footer-text: #4d5760;
+
+  /* Inputs */
   --input-bg: #ffffff;
   --select-bg: #ffffff;
+
+  /* Unmatched tag — amber, accessible on its bg */
   --unmatched-tag-bg: #fff3e0;
-  --unmatched-tag-color: #e65100;
+  --unmatched-tag-color: #7a4000; /* ~7.1:1 on #fff3e0 — AA */
 }
 
 [data-theme="dark"] {
@@ -458,21 +485,60 @@ body {
   font-size: 0.8rem;
 }
 
+.episode-info {
+  color: var(--text-secondary);
+  font-size: 0.78rem;
+  margin: -2px 0 6px;
+}
+
+.episode-info.multi-episode {
+  cursor: help;
+  text-decoration: underline dotted;
+  position: relative;
+}
+
+.episode-info.multi-episode:hover::after {
+  content: attr(data-tooltip);
+  position: absolute;
+  left: 0;
+  top: 100%;
+  z-index: 20;
+  background: var(--surface);
+  color: var(--text-primary);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 8px 10px;
+  font-size: 0.75rem;
+  white-space: pre-line;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+  max-width: 320px;
+  pointer-events: none;
+}
+
 /* ===== Detail Row (Inline) ===== */
 .download-details {
   display: flex;
   flex-wrap: wrap;
-  gap: 4px 14px;
+  gap: 4px 6px;
   padding-top: 6px;
   border-top: 1px solid var(--border);
   align-items: center;
 }
 
 .detail-item {
-  display: flex;
+  display: inline-flex;
   align-items: baseline;
-  gap: 4px;
+  gap: 3px;
   font-size: 0.78rem;
+  background: var(--bg-secondary, rgba(0,0,0,0.04));
+  border-radius: 4px;
+  padding: 2px 6px;
+  white-space: nowrap;
+}
+
+.detail-item.availability-warning .detail-value {
+  color: var(--danger, #e53e3e);
+  font-weight: 700;
 }
 
 .detail-label {
@@ -491,10 +557,17 @@ body {
 /* ===== Progress Bar (Compact) ===== */
 .progress-item {
   flex-basis: 100%;
+  display: flex;
+  align-items: center;
+  background: none;
+  padding: 0;
+  white-space: normal;
+  border-radius: 0;
 }
 
 .progress-container {
   display: flex;
+  flex: 1;
   align-items: center;
   gap: 8px;
 }
@@ -510,13 +583,15 @@ body {
 }
 
 .progress-segment {
+  position: absolute;
+  top: 0;
+  left: 0;
   height: 100%;
   transition: width 0.3s ease;
 }
 
 .progress-segment.downloaded {
   background: linear-gradient(90deg, var(--progress-fill-start) 0%, var(--progress-fill-end) 100%);
-  float: left;
 }
 
 .progress-text {
@@ -534,6 +609,293 @@ body {
   word-break: break-word;
 }
 
+/* ===== Main Tabs ===== */
+.main-tabs {
+  max-width: 1200px;
+  margin: 16px auto 0;
+  padding: 0 16px;
+}
+
+.tab-bar {
+  display: flex;
+  gap: 4px;
+  border-bottom: 2px solid var(--border);
+  margin-bottom: 0;
+}
+
+.tab-btn {
+  background: none;
+  border: none;
+  border-bottom: 3px solid transparent;
+  margin-bottom: -2px;
+  padding: 10px 20px;
+  font-size: 0.95rem;
+  font-weight: 600;
+  color: var(--text-secondary);
+  cursor: pointer;
+  transition: color 0.2s, border-color 0.2s;
+  border-radius: 4px 4px 0 0;
+}
+
+.tab-btn:hover {
+  color: var(--text-primary);
+  background: var(--surface);
+}
+
+.tab-btn.active {
+  color: var(--accent);
+  border-bottom-color: var(--accent);
+  background: var(--surface);
+}
+
+.tab-panel {
+  padding-top: 0;
+}
+
+/* ===== Recently Completed History ===== */
+.history-container {
+  max-width: unset;
+  margin: 0;
+  padding: 0;
+}
+
+.history-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 12px;
+  flex-wrap: wrap;
+}
+
+.history-header h2 {
+  margin: 0;
+  font-size: 1.2rem;
+  color: var(--text-primary);
+  flex: 1 1 auto;
+}
+
+.history-controls {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: nowrap;
+}
+
+.history-days-label {
+  font-size: 0.85rem;
+  color: var(--text-secondary);
+}
+
+.history-days-input {
+  width: 52px;
+  padding: 3px 6px;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: var(--surface);
+  color: var(--text-primary);
+  font-size: 0.85rem;
+  text-align: center;
+}
+
+.history-refresh-btn {
+  background: none;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  color: var(--text-secondary);
+  cursor: pointer;
+  font-size: 1rem;
+  padding: 2px 7px;
+  line-height: 1.4;
+  transition: background 0.15s, color 0.15s;
+}
+
+.history-refresh-btn:hover {
+  background: var(--hover-bg);
+  color: var(--text-primary);
+}
+
+.history-toggle-label {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 0.82rem;
+  color: var(--text-secondary);
+  cursor: pointer;
+  user-select: none;
+  margin-left: 4px;
+  position: relative;
+}
+
+.history-toggle-label[data-tooltip]:hover::after {
+  content: attr(data-tooltip);
+  position: absolute;
+  left: 0;
+  top: calc(100% + 6px);
+  z-index: 20;
+  background: var(--surface);
+  color: var(--text-primary);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 8px 10px;
+  font-size: 0.75rem;
+  white-space: pre-line;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+  max-width: 280px;
+  pointer-events: none;
+}
+
+.history-toggle-label input[type="checkbox"] {
+  cursor: pointer;
+  accent-color: var(--accent, #2980b9);
+}
+
+.history-loading,
+.history-error,
+.no-history {
+  color: var(--text-secondary);
+  font-size: 0.9rem;
+  padding: 8px 0;
+}
+
+.history-error {
+  color: var(--error, #e74c3c);
+}
+
+.history-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.history-card {
+  display: flex;
+  gap: 12px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 10px 12px;
+  transition: background 0.2s;
+  align-items: flex-start;
+}
+
+.history-card.failed {
+  border-left: 3px solid var(--error, #e74c3c);
+}
+
+.history-card.imported {
+  border-left: 3px solid var(--success, #27ae60);
+}
+
+.history-cover {
+  flex: 0 0 48px;
+  width: 48px;
+}
+
+.history-cover img {
+  width: 48px;
+  height: 68px;
+  object-fit: cover;
+  border-radius: 4px;
+  display: block;
+}
+
+.history-info {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.history-card-header {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 5px;
+  align-items: center;
+  margin-bottom: 4px;
+}
+
+.history-type-badge,
+.history-outcome-badge,
+.history-instance-badge,
+.history-upgrade-badge {
+  font-size: 0.72rem;
+  font-weight: 600;
+  padding: 2px 7px;
+  border-radius: 10px;
+  white-space: nowrap;
+}
+
+.history-upgrade-badge {
+  background: #e67e22;
+  color: #fff;
+  cursor: default;
+}
+
+.history-type-badge.series {
+  background: var(--badge-series-bg, #2980b9);
+  color: #fff;
+}
+
+.history-type-badge.movie {
+  background: var(--badge-movie-bg, #8e44ad);
+  color: #fff;
+}
+
+.history-outcome-badge.imported {
+  background: var(--success, #27ae60);
+  color: #fff;
+}
+
+.history-outcome-badge.failed {
+  background: var(--error, #e74c3c);
+  color: #fff;
+}
+
+.history-instance-badge {
+  background: var(--tag-bg, #ecf0f1);
+  color: var(--text-secondary);
+  border: 1px solid var(--border);
+}
+
+.history-title {
+  font-size: 0.9rem;
+  font-weight: 600;
+  margin: 0 0 2px;
+  color: var(--text-primary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.history-media-name {
+  font-size: 0.82rem;
+  color: var(--text-secondary);
+  margin: 0 0 4px;
+}
+
+.history-details {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 5px;
+  margin-top: 4px;
+}
+
+.history-failure-message {
+  font-size: 0.78rem;
+  color: var(--error, #e74c3c);
+  background: var(--error-bg, rgba(231, 76, 60, 0.08));
+  border-radius: 4px;
+  padding: 3px 7px;
+  flex-basis: 100%;
+}
+
+@media (max-width: 480px) {
+  .history-cover {
+    display: none;
+  }
+  .history-title {
+    white-space: normal;
+  }
+}
+
 /* ===== Footer ===== */
 .app-footer {
   margin-top: 12px;
@@ -546,6 +908,41 @@ body {
   opacity: 0.8;
 }
 
+.app-version {
+  font-size: 0.72rem;
+  opacity: 0.5;
+  margin-top: 4px;
+  color: inherit;
+  text-decoration: none;
+  display: inline-block;
+}
+
+.app-version:hover {
+  opacity: 0.8;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.title-link {
+  color: inherit;
+  text-decoration: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.title-link:hover {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+.title-logo {
+  width: 56px;
+  height: 56px;
+  display: block;
+  flex-shrink: 0;
+}
+
 /* ===== Login ===== */
 .login-container {
   display: flex;
@@ -740,20 +1137,54 @@ body {
   position: absolute;
   top: calc(100% + 6px);
   left: 0;
-  background: #424242;
-  color: #fff;
-  padding: 8px 12px;
+  z-index: 20;
+  background: var(--surface);
+  color: var(--text-primary);
+  border: 1px solid var(--border);
   border-radius: 6px;
-  font-size: 0.7rem;
+  padding: 8px 10px;
+  font-size: 0.75rem;
   font-weight: 400;
   white-space: pre-line;
   max-width: 320px;
-  z-index: 100;
-  box-shadow: 0 2px 8px rgba(0,0,0,0.25);
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
   line-height: 1.4;
   pointer-events: none;
 }
 
+.blocklist-search-btn {
+  font-size: 0.68rem;
+  font-weight: 600;
+  padding: 2px 8px;
+  border-radius: 10px;
+  border: 1px solid var(--error, #e74c3c);
+  background: transparent;
+  color: var(--error, #e74c3c);
+  cursor: pointer;
+  white-space: nowrap;
+  transition: background 0.15s, color 0.15s;
+}
+
+.blocklist-search-btn:hover:not(:disabled) {
+  background: var(--error, #e74c3c);
+  color: #fff;
+}
+
+.blocklist-search-btn:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
+.blocklist-search-btn.success {
+  border-color: var(--success, #27ae60);
+  color: var(--success, #27ae60);
+}
+
+.blocklist-search-btn.error {
+  background: var(--error, #e74c3c);
+  color: #fff;
+}
+
 .download-user-badge {
   padding: 2px 8px;
   border-radius: 10px;
@@ -1021,11 +1452,6 @@ body {
     width: 40px;
   }
 
-  .download-details {
-    flex-direction: column;
-    gap: 2px;
-  }
-
   .progress-container {
     flex-wrap: wrap;
   }

server/app.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Express application factory — imported by both server/index.js (production)
  * and the test suite. Keeping app creation separate from app.listen() means
@@ -16,6 +17,7 @@ const sonarrRoutes = require('./routes/sonarr');
 const radarrRoutes = require('./routes/radarr');
 const embyRoutes = require('./routes/emby');
 const dashboardRoutes = require('./routes/dashboard');
+const historyRoutes = require('./routes/history');
 const authRoutes = require('./routes/auth');
 const verifyCsrf = require('./middleware/verifyCsrf');
 
@@ -50,7 +52,7 @@ function createApp({ skipRateLimits = false } = {}) {
           baseUri: ["'self'"],
           frameAncestors: ["'none'"],
           formAction: ["'self'"],
-          upgradeInsecureRequests: process.env.NODE_ENV === 'production' ? [] : null
+          upgradeInsecureRequests: process.env.TRUST_PROXY ? [] : null
         }
       },
       hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
@@ -100,6 +102,7 @@ function createApp({ skipRateLimits = false } = {}) {
   app.use('/api/radarr', radarrRoutes);
   app.use('/api/emby', embyRoutes);
   app.use('/api/dashboard', dashboardRoutes);
+  app.use('/api/history', historyRoutes);
 
   // Global error handler
   // eslint-disable-next-line no-unused-vars

server/clients/DownloadClient.js

@@ -0,0 +1,103 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+
+/**
+ * Abstract base class for all download clients.
+ * Defines the common interface that all download clients must implement.
+ */
+class DownloadClient {
+  /**
+   * @param {Object} instanceConfig - Configuration for this client instance
+   * @param {string} instanceConfig.id - Unique identifier for this instance
+   * @param {string} instanceConfig.name - Display name for this instance
+   * @param {string} instanceConfig.url - Base URL for the client API
+   * @param {string} [instanceConfig.apiKey] - API key for authentication (if applicable)
+   * @param {string} [instanceConfig.username] - Username for authentication (if applicable)
+   * @param {string} [instanceConfig.password] - Password for authentication (if applicable)
+   */
+  constructor(instanceConfig) {
+    if (this.constructor === DownloadClient) {
+      throw new Error('DownloadClient is an abstract class and cannot be instantiated directly');
+    }
+    
+    this.id = instanceConfig.id;
+    this.name = instanceConfig.name;
+    this.url = instanceConfig.url;
+    this.apiKey = instanceConfig.apiKey;
+    this.username = instanceConfig.username;
+    this.password = instanceConfig.password;
+  }
+
+  /**
+   * Get the client type identifier (e.g., 'qbittorrent', 'sabnzbd', 'transmission')
+   * @returns {string} The client type
+   */
+  getClientType() {
+    throw new Error('getClientType() must be implemented by subclass');
+  }
+
+  /**
+   * Get the unique instance ID
+   * @returns {string} The instance ID
+   */
+  getInstanceId() {
+    return this.id;
+  }
+
+  /**
+   * Test connection to the download client
+   * @returns {Promise<boolean>} True if connection is successful
+   */
+  async testConnection() {
+    throw new Error('testConnection() must be implemented by subclass');
+  }
+
+  /**
+   * Get active downloads from this client
+   * @returns {Promise<Array<NormalizedDownload>>} Array of normalized download objects
+   */
+  async getActiveDownloads() {
+    throw new Error('getActiveDownloads() must be implemented by subclass');
+  }
+
+  /**
+   * Optional: Get client status information
+   * @returns {Promise<Object|null>} Client status object or null if not supported
+   */
+  async getClientStatus() {
+    return null; // Default implementation - optional method
+  }
+
+  /**
+   * Normalize a download object to the standard schema
+   * @param {Object} download - Raw download object from client
+   * @returns {NormalizedDownload} Normalized download object
+   */
+  normalizeDownload(download) {
+    throw new Error('normalizeDownload() must be implemented by subclass');
+  }
+}
+
+/**
+ * @typedef {Object} NormalizedDownload
+ * @property {string} id - Client-specific unique ID
+ * @property {string} title - Download title/name
+ * @property {'usenet'|'torrent'} type - Download type
+ * @property {string} client - Client identifier ('sabnzbd', 'qbittorrent', 'transmission', etc.)
+ * @property {string} instanceId - Instance identifier
+ * @property {string} instanceName - Instance display name
+ * @property {string} status - Normalized status (Downloading, Seeding, Paused, etc.)
+ * @property {number} progress - Progress percentage (0-100)
+ * @property {number} size - Total size in bytes
+ * @property {number} downloaded - Downloaded bytes
+ * @property {number} speed - Current speed in bytes/sec
+ * @property {number|null} eta - Estimated time remaining in seconds, null if unknown
+ * @property {string|undefined} category - Download category (optional)
+ * @property {string[]|undefined} tags - Download tags (optional)
+ * @property {string|undefined} savePath - Save path (optional)
+ * @property {string|undefined} addedOn - Added timestamp (optional)
+ * @property {number|undefined} arrQueueId - Sonarr/Radarr queue ID (optional)
+ * @property {'series'|'movie'|undefined} arrType - Sonarr/Radarr type (optional)
+ * @property {any|undefined} raw - Original client response (escape hatch)
+ */
+
+module.exports = DownloadClient;

server/clients/QBittorrentClient.js

@@ -0,0 +1,256 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const axios = require('axios');
+const DownloadClient = require('./DownloadClient');
+const { logToFile } = require('../utils/logger');
+
+class QBittorrentClient extends DownloadClient {
+  constructor(instance) {
+    super(instance);
+    this.authCookie = null;
+    // Sync API incremental state
+    this.lastRid = 0;
+    this.torrentMap = new Map();
+    this.fallbackThisCycle = false;
+  }
+
+  getClientType() {
+    return 'qbittorrent';
+  }
+
+  async testConnection() {
+    try {
+      await this.login();
+      // Try a simple API call to verify connection
+      await this.makeRequest('/api/v2/app/version');
+      logToFile(`[qBittorrent:${this.name}] Connection test successful`);
+      return true;
+    } catch (error) {
+      logToFile(`[qBittorrent:${this.name}] Connection test failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  async login() {
+    try {
+      logToFile(`[qBittorrent:${this.name}] Attempting login...`);
+      const response = await axios.post(`${this.url}/api/v2/auth/login`, 
+        `username=${encodeURIComponent(this.username)}&password=${encodeURIComponent(this.password)}`,
+        {
+          headers: {
+            'Content-Type': 'application/x-www-form-urlencoded'
+          },
+          maxRedirects: 0,
+          validateStatus: (status) => status >= 200 && status < 400
+        }
+      );
+      
+      if (response.headers['set-cookie']) {
+        this.authCookie = response.headers['set-cookie'][0];
+        logToFile(`[qBittorrent:${this.name}] Login successful`);
+        return true;
+      }
+      
+      logToFile(`[qBittorrent:${this.name}] Login failed - no cookie`);
+      return false;
+    } catch (error) {
+      logToFile(`[qBittorrent:${this.name}] Login error: ${error.message}`);
+      return false;
+    }
+  }
+
+  async makeRequest(endpoint, config = {}) {
+    const url = `${this.url}${endpoint}`;
+    
+    if (!this.authCookie) {
+      const loggedIn = await this.login();
+      if (!loggedIn) {
+        throw new Error(`Failed to authenticate with ${this.name}`);
+      }
+    }
+    
+    try {
+      const response = await axios.get(url, {
+        ...config,
+        headers: {
+          ...config.headers,
+          'Cookie': this.authCookie
+        }
+      });
+      return response;
+    } catch (error) {
+      // If unauthorized, try re-authenticating once
+      if (error.response && error.response.status === 403) {
+        logToFile(`[qBittorrent:${this.name}] Auth expired, re-authenticating...`);
+        this.authCookie = null;
+        const loggedIn = await this.login();
+        if (loggedIn) {
+          return axios.get(url, {
+            ...config,
+            headers: {
+              ...config.headers,
+              'Cookie': this.authCookie
+            }
+          });
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Fetches incremental torrent data using the qBittorrent Sync API.
+   */
+  async getMainData() {
+    const response = await this.makeRequest(`/api/v2/sync/maindata?rid=${this.lastRid}`);
+    const data = response.data;
+
+    if (data.full_update) {
+      // Full refresh: rebuild the entire map
+      this.torrentMap.clear();
+      if (data.torrents) {
+        for (const [hash, props] of Object.entries(data.torrents)) {
+          this.torrentMap.set(hash, { ...props, hash });
+        }
+      }
+    } else {
+      // Delta update: merge changed fields into existing torrent objects
+      if (data.torrents) {
+        for (const [hash, delta] of Object.entries(data.torrents)) {
+          const existing = this.torrentMap.get(hash) || { hash };
+          this.torrentMap.set(hash, { ...existing, ...delta });
+        }
+      }
+    }
+
+    // Remove torrents that the server reports as deleted
+    if (data.torrents_removed) {
+      for (const hash of data.torrents_removed) {
+        this.torrentMap.delete(hash);
+      }
+    }
+
+    // Ensure every torrent has a computed 'completed' field for downstream consumers
+    for (const torrent of this.torrentMap.values()) {
+      if (torrent.completed === undefined && torrent.size !== undefined && torrent.progress !== undefined) {
+        torrent.completed = Math.round(torrent.size * torrent.progress);
+      }
+    }
+
+    this.lastRid = data.rid;
+    return Array.from(this.torrentMap.values());
+  }
+
+  /**
+   * Legacy full-list fetch. Used as a fallback when the Sync API fails.
+   */
+  async getTorrentsLegacy() {
+    try {
+      const response = await this.makeRequest('/api/v2/torrents/info');
+      logToFile(`[qBittorrent:${this.name}] Retrieved ${response.data.length} torrents (legacy)`);
+      return response.data;
+    } catch (error) {
+      logToFile(`[qBittorrent:${this.name}] Error fetching torrents (legacy): ${error.message}`);
+      throw error;
+    }
+  }
+
+  async getActiveDownloads() {
+    try {
+      if (this.fallbackThisCycle) {
+        logToFile(`[qBittorrent:${this.name}] Already fell back this cycle, using legacy`);
+        const torrents = await this.getTorrentsLegacy();
+        return torrents.map(torrent => this.normalizeDownload(torrent));
+      }
+
+      const torrents = await this.getMainData();
+      logToFile(`[qBittorrent:${this.name}] Sync: ${torrents.length} torrents (rid=${this.lastRid})`);
+      return torrents.map(torrent => this.normalizeDownload(torrent));
+    } catch (error) {
+      logToFile(`[qBittorrent:${this.name}] Sync failed, falling back to legacy: ${error.message}`);
+      this.fallbackThisCycle = true;
+      try {
+        const torrents = await this.getTorrentsLegacy();
+        return torrents.map(torrent => this.normalizeDownload(torrent));
+      } catch (fallbackError) {
+        logToFile(`[qBittorrent:${this.name}] Fallback also failed: ${fallbackError.message}`);
+        return [];
+      }
+    }
+  }
+
+  async getClientStatus() {
+    try {
+      const response = await this.makeRequest('/api/v2/sync/maindata');
+      const data = response.data;
+      
+      return {
+        serverState: data.server_state || {},
+        rid: data.rid,
+        fullUpdate: data.full_update
+      };
+    } catch (error) {
+      logToFile(`[qBittorrent:${this.name}] Error getting client status: ${error.message}`);
+      return null;
+    }
+  }
+
+  normalizeDownload(torrent) {
+    const totalSize = torrent.size;
+    const downloadedSize = torrent.completed || Math.round(torrent.size * torrent.progress);
+    const progress = torrent.progress * 100;
+    
+    // Map qBittorrent states to our normalized status
+    const stateMap = {
+      'downloading': 'Downloading',
+      'stalledDL': 'Downloading',
+      'metaDL': 'Downloading',
+      'forcedDL': 'Downloading',
+      'allocating': 'Downloading',
+      'uploading': 'Seeding',
+      'stalledUP': 'Seeding',
+      'forcedUP': 'Seeding',
+      'queuedUP': 'Queued',
+      'queuedDL': 'Queued',
+      'checkingUP': 'Checking',
+      'checkingDL': 'Checking',
+      'checkingResumeData': 'Checking',
+      'moving': 'Moving',
+      'pausedUP': 'Paused',
+      'pausedDL': 'Paused',
+      'stoppedUP': 'Stopped',
+      'stoppedDL': 'Stopped',
+      'error': 'Error',
+      'missingFiles': 'Error',
+      'unknown': 'Unknown'
+    };
+    
+    const status = stateMap[torrent.state] || torrent.state;
+    
+    return {
+      id: torrent.hash,
+      title: torrent.name,
+      type: 'torrent',
+      client: 'qbittorrent',
+      instanceId: this.id,
+      instanceName: this.name,
+      status: status,
+      progress: Math.round(progress),
+      size: totalSize,
+      downloaded: downloadedSize,
+      speed: torrent.dlspeed,
+      eta: torrent.eta < 0 || torrent.eta === 8640000 ? null : torrent.eta,
+      category: torrent.category || undefined,
+      tags: torrent.tags ? torrent.tags.split(',').filter(tag => tag.trim()) : [],
+      savePath: torrent.content_path || torrent.save_path || undefined,
+      addedOn: torrent.added_on ? new Date(torrent.added_on * 1000).toISOString() : undefined,
+      raw: torrent
+    };
+  }
+
+  // Reset fallback flag (called by registry at start of each poll cycle)
+  resetFallbackFlag() {
+    this.fallbackThisCycle = false;
+  }
+}
+
+module.exports = QBittorrentClient;

server/clients/RTorrentClient.js

@@ -0,0 +1,185 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const xmlrpc = require('xmlrpc');
+const DownloadClient = require('./DownloadClient');
+const { logToFile } = require('../utils/logger');
+
+/**
+ * rTorrent download client implementation.
+ * Communicates via XML-RPC over HTTP.
+ * Supports HTTP Basic Auth when username/password are configured.
+ * The URL field must include the full XML-RPC endpoint path (e.g., http://rtorrent.local:8080/RPC2 or https://user.whatbox.ca/xmlrpc).
+ */
+class RTorrentClient extends DownloadClient {
+  constructor(instance) {
+    super(instance);
+    this._createClient();
+  }
+
+  _createClient() {
+    const clientOptions = { url: this.url };
+
+    if (this.username && this.password) {
+      clientOptions.headers = {
+        Authorization: `Basic ${Buffer.from(`${this.username}:${this.password}`).toString('base64')}`
+      };
+    }
+
+    this.client = xmlrpc.createClient(clientOptions);
+  }
+
+  getClientType() {
+    return 'rtorrent';
+  }
+
+  async testConnection() {
+    try {
+      await this._methodCall('system.client_version');
+      logToFile(`[rtorrent:${this.name}] Connection test successful`);
+      return true;
+    } catch (error) {
+      logToFile(`[rtorrent:${this.name}] Connection test failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Wrap xmlrpc methodCall in a Promise.
+   * @param {string} method - XML-RPC method name
+   * @param {Array} params - Method parameters
+   * @returns {Promise<any>}
+   */
+  _methodCall(method, params = []) {
+    return new Promise((resolve, reject) => {
+      this.client.methodCall(method, params, (error, value) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve(value);
+        }
+      });
+    });
+  }
+
+  async getActiveDownloads() {
+    try {
+      const torrents = await this._methodCall('d.multicall2', [
+        '',
+        'd.hash=',
+        'd.name=',
+        'd.size_bytes=',
+        'd.completed_bytes=',
+        'd.down.rate=',
+        'd.up.rate=',
+        'd.state=',
+        'd.is_active=',
+        'd.is_hash_checking=',
+        'd.directory=',
+        'd.custom1='
+      ]);
+
+      logToFile(`[rtorrent:${this.name}] Retrieved ${torrents.length} torrents`);
+      return torrents.map(torrent => this.normalizeDownload(torrent));
+    } catch (error) {
+      logToFile(`[rtorrent:${this.name}] Error fetching torrents: ${error.message}`);
+      return [];
+    }
+  }
+
+  async getClientStatus() {
+    try {
+      const [downRate, upRate] = await Promise.all([
+        this._methodCall('throttle.global_down.rate'),
+        this._methodCall('throttle.global_up.rate')
+      ]);
+
+      return {
+        globalDownRate: downRate,
+        globalUpRate: upRate
+      };
+    } catch (error) {
+      logToFile(`[rtorrent:${this.name}] Error getting client status: ${error.message}`);
+      return null;
+    }
+  }
+
+  normalizeDownload(torrent) {
+    const [
+      hash,
+      name,
+      sizeBytes,
+      completedBytes,
+      downRate,
+      upRate,
+      state,
+      isActive,
+      isHashChecking,
+      directory,
+      custom1
+    ] = torrent;
+
+    const status = this._mapStatus(state, isActive, isHashChecking, completedBytes, sizeBytes);
+    const progress = sizeBytes > 0 ? Math.round((completedBytes / sizeBytes) * 100) : 0;
+
+    // Calculate ETA when actively downloading
+    let eta = null;
+    if (status === 'Downloading' && downRate > 0 && completedBytes < sizeBytes) {
+      eta = Math.round((sizeBytes - completedBytes) / downRate);
+    }
+
+    const arrInfo = this._extractArrInfo(name);
+
+    return {
+      id: hash,
+      title: name,
+      type: 'torrent',
+      client: 'rtorrent',
+      instanceId: this.id,
+      instanceName: this.name,
+      status,
+      progress,
+      size: sizeBytes,
+      downloaded: completedBytes,
+      speed: status === 'Seeding' ? upRate : downRate,
+      eta,
+      category: custom1 || undefined,
+      tags: custom1 ? [custom1] : [],
+      savePath: directory || undefined,
+      addedOn: undefined, // rtorrent does not expose added time via multicall2
+      arrQueueId: arrInfo.queueId,
+      arrType: arrInfo.type,
+      raw: torrent
+    };
+  }
+
+  _mapStatus(state, isActive, isHashChecking, completedBytes, sizeBytes) {
+    if (isHashChecking === 1) {
+      return 'Checking';
+    }
+
+    if (state === 0) {
+      return 'Stopped';
+    }
+
+    if (isActive === 1) {
+      return completedBytes >= sizeBytes && sizeBytes > 0 ? 'Seeding' : 'Downloading';
+    }
+
+    return 'Paused';
+  }
+
+  _extractArrInfo(filename) {
+    const seriesMatch = filename.match(/[-\s]S(\d{2})E(\d{2})/i);
+    if (seriesMatch) {
+      return { type: 'series' };
+    }
+
+    const movieMatch = filename.match(/\((\d{4})\)/);
+    if (movieMatch) {
+      return { type: 'movie' };
+    }
+
+    return {};
+  }
+}
+
+module.exports = RTorrentClient;

server/clients/SABnzbdClient.js

@@ -0,0 +1,239 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const axios = require('axios');
+const DownloadClient = require('./DownloadClient');
+const { logToFile } = require('../utils/logger');
+
+class SABnzbdClient extends DownloadClient {
+  constructor(instance) {
+    super(instance);
+  }
+
+  getClientType() {
+    return 'sabnzbd';
+  }
+
+  async testConnection() {
+    try {
+      const response = await this.makeRequest('', { mode: 'version' });
+      logToFile(`[SABnzbd:${this.name}] Connection test successful, version: ${response.data.version}`);
+      return true;
+    } catch (error) {
+      logToFile(`[SABnzbd:${this.name}] Connection test failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  async makeRequest(additionalParams = {}, config = {}) {
+    const params = {
+      output: 'json',
+      apikey: this.apiKey,
+      ...additionalParams
+    };
+
+    try {
+      const response = await axios.get(`${this.url}/api`, {
+        params,
+        ...config
+      });
+      return response;
+    } catch (error) {
+      logToFile(`[SABnzbd:${this.name}] API request failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  async getActiveDownloads() {
+    try {
+      // Get both queue and history to provide complete picture
+      const [queueResponse, historyResponse] = await Promise.all([
+        this.makeRequest({ mode: 'queue' }),
+        this.makeRequest({ mode: 'history', limit: 10 })
+      ]);
+
+      const queueData = queueResponse.data;
+      const historyData = historyResponse.data;
+
+      const downloads = [];
+
+      // Process active queue items
+      if (queueData.queue && queueData.queue.slots) {
+        for (const slot of queueData.queue.slots) {
+          downloads.push(this.normalizeDownload(slot, 'queue'));
+        }
+      }
+
+      // Process recent history items (last 10)
+      if (historyData.history && historyData.history.slots) {
+        for (const slot of historyData.history.slots) {
+          downloads.push(this.normalizeDownload(slot, 'history'));
+        }
+      }
+
+      logToFile(`[SABnzbd:${this.name}] Retrieved ${downloads.length} downloads`);
+      return downloads;
+    } catch (error) {
+      logToFile(`[SABnzbd:${this.name}] Error fetching downloads: ${error.message}`);
+      return [];
+    }
+  }
+
+  async getClientStatus() {
+    try {
+      const response = await this.makeRequest({ mode: 'queue' });
+      const queueData = response.data.queue;
+      
+      if (!queueData) return null;
+
+      return {
+        status: queueData.status,
+        speed: queueData.speed,
+        kbpersec: queueData.kbpersec,
+        sizeleft: queueData.sizeleft,
+        mbleft: queueData.mbleft,
+        mb: queueData.mb,
+        diskspace1: queueData.diskspace1,
+        diskspace2: queueData.diskspace2,
+        loadavg: queueData.loadavg,
+        pause_int: queueData.pause_int
+      };
+    } catch (error) {
+      logToFile(`[SABnzbd:${this.name}] Error getting client status: ${error.message}`);
+      return null;
+    }
+  }
+
+  normalizeDownload(slot, source) {
+    const isHistory = source === 'history';
+    
+    // Map SABnzbd statuses to normalized status
+    const statusMap = {
+      'Downloading': 'Downloading',
+      'Paused': 'Paused',
+      'Waiting': 'Queued',
+      'Completed': 'Completed',
+      'Failed': 'Error',
+      'Verifying': 'Checking',
+      'Extracting': 'Extracting',
+      'Moving': 'Moving',
+      'QuickCheck': 'Checking',
+      'Repairing': 'Repairing'
+    };
+
+    const status = statusMap[slot.status] || slot.status;
+
+    // Calculate progress
+    let progress = 0;
+    let downloaded = 0;
+    let size = 0;
+
+    if (slot.mb && slot.mbleft !== undefined) {
+      size = slot.mb * 1024 * 1024; // Convert MB to bytes
+      downloaded = (slot.mb - slot.mbleft) * 1024 * 1024;
+      progress = slot.mb > 0 ? ((slot.mb - slot.mbleft) / slot.mb) * 100 : 0;
+    } else if (slot.size) {
+      // Try to parse size string (e.g., "1.5 GB")
+      const sizeMatch = slot.size.match(/^([\d.]+)\s*(\w+)$/i);
+      if (sizeMatch) {
+        const [, sizeValue, sizeUnit] = sizeMatch;
+        const multiplier = this.getUnitMultiplier(sizeUnit);
+        size = parseFloat(sizeValue) * multiplier;
+        
+        if (slot.sizeleft) {
+          const leftMatch = slot.sizeleft.match(/^([\d.]+)\s*(\w+)$/i);
+          if (leftMatch) {
+            const [, leftValue, leftUnit] = leftMatch;
+            const leftMultiplier = this.getUnitMultiplier(leftUnit);
+            downloaded = size - (parseFloat(leftValue) * leftMultiplier);
+            progress = size > 0 ? (downloaded / size) * 100 : 0;
+          }
+        }
+      }
+    }
+
+    // Extract Sonarr/Radarr info from nzb_name if present
+    const arrInfo = this.extractArrInfo(slot.nzb_name || slot.filename || '');
+
+    return {
+      id: slot.nzo_id || slot.id,
+      title: slot.filename || slot.nzb_name || 'Unknown',
+      type: 'usenet',
+      client: 'sabnzbd',
+      instanceId: this.id,
+      instanceName: this.name,
+      status: status,
+      progress: Math.round(progress),
+      size: Math.round(size),
+      downloaded: Math.round(downloaded),
+      speed: slot.kbpersec ? slot.kbpersec * 1024 : 0, // Convert KB/s to bytes/s
+      eta: this.calculateEta(slot.timeleft || slot.eta),
+      category: slot.cat || undefined,
+      tags: slot.labels ? slot.labels.split(',').filter(tag => tag.trim()) : [],
+      savePath: slot.final_name || undefined,
+      addedOn: slot.added ? new Date(slot.added * 1000).toISOString() : undefined,
+      arrQueueId: arrInfo.queueId,
+      arrType: arrInfo.type,
+      raw: { ...slot, source }
+    };
+  }
+
+  getUnitMultiplier(unit) {
+    const unitMap = {
+      'b': 1,
+      'byte': 1,
+      'bytes': 1,
+      'kb': 1024,
+      'k': 1024,
+      'mb': 1024 * 1024,
+      'm': 1024 * 1024,
+      'gb': 1024 * 1024 * 1024,
+      'g': 1024 * 1024 * 1024,
+      'tb': 1024 * 1024 * 1024 * 1024,
+      't': 1024 * 1024 * 1024 * 1024
+    };
+    return unitMap[unit.toLowerCase()] || 1;
+  }
+
+  calculateEta(timeLeft) {
+    if (!timeLeft || timeLeft === '0:00' || timeLeft === 'unknown') {
+      return null;
+    }
+
+    // Parse time in various formats: "0:05:30", "15:30", "330"
+    const parts = timeLeft.split(':').reverse();
+    let totalSeconds = 0;
+
+    if (parts.length === 1) {
+      // Just seconds
+      totalSeconds = parseInt(parts[0], 10);
+    } else if (parts.length === 2) {
+      // MM:SS
+      totalSeconds = parseInt(parts[0], 10) + parseInt(parts[1], 10) * 60;
+    } else if (parts.length === 3) {
+      // HH:MM:SS
+      totalSeconds = parseInt(parts[0], 10) + parseInt(parts[1], 10) * 60 + parseInt(parts[2], 10) * 3600;
+    }
+
+    return isNaN(totalSeconds) ? null : totalSeconds;
+  }
+
+  extractArrInfo(filename) {
+    // Try to extract Sonarr/Radarr info from filename patterns
+    // This is a simple implementation - could be enhanced with regex patterns
+    
+    // Look for patterns like "Series Name - S01E02 - Episode Title"
+    const seriesMatch = filename.match(/[-\s]S(\d{2})E(\d{2})/i);
+    if (seriesMatch) {
+      return { type: 'series' };
+    }
+
+    // Look for movie year patterns like "Movie Title (2023)"
+    const movieMatch = filename.match(/\((\d{4})\)/);
+    if (movieMatch && !seriesMatch) {
+      return { type: 'movie' };
+    }
+
+    return {};
+  }
+}
+
+module.exports = SABnzbdClient;

server/clients/TransmissionClient.js

@@ -0,0 +1,181 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const axios = require('axios');
+const DownloadClient = require('./DownloadClient');
+const { logToFile } = require('../utils/logger');
+
+class TransmissionClient extends DownloadClient {
+  constructor(instance) {
+    super(instance);
+    this.sessionId = null;
+    this.rpcUrl = `${this.url}/transmission/rpc`;
+  }
+
+  getClientType() {
+    return 'transmission';
+  }
+
+  async testConnection() {
+    try {
+      await this.makeRequest('session-get');
+      logToFile(`[Transmission:${this.name}] Connection test successful`);
+      return true;
+    } catch (error) {
+      logToFile(`[Transmission:${this.name}] Connection test failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  async makeRequest(method, arguments_ = {}, config = {}) {
+    const payload = {
+      method,
+      arguments: arguments_
+    };
+
+    const headers = {
+      'Content-Type': 'application/json'
+    };
+
+    if (this.sessionId) {
+      headers['X-Transmission-Session-Id'] = this.sessionId;
+    }
+
+    try {
+      const response = await axios.post(this.rpcUrl, payload, {
+        headers,
+        ...config
+      });
+
+      if (response.data.result !== 'success') {
+        throw new Error(`Transmission RPC error: ${response.data.result}`);
+      }
+
+      return response;
+    } catch (error) {
+      // Handle session ID conflict (409 Conflict)
+      if (error.response && error.response.status === 409) {
+        const sessionId = error.response.headers['x-transmission-session-id'];
+        if (sessionId) {
+          this.sessionId = sessionId;
+          logToFile(`[Transmission:${this.name}] Updated session ID`);
+          return this.makeRequest(method, arguments_, config);
+        }
+      }
+      logToFile(`[Transmission:${this.name}] RPC request failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  async getActiveDownloads() {
+    try {
+      // Get all torrents with detailed fields
+      const response = await this.makeRequest('torrent-get', {
+        fields: [
+          'id', 'name', 'hashString', 'status', 'totalSize', 'sizeWhenDone',
+          'leftUntilDone', 'rateDownload', 'rateUpload', 'eta', 'downloadedEver',
+          'uploadedEver', 'percentDone', 'addedDate', 'doneDate', 'trackerStats',
+          'labels', 'downloadDir', 'error', 'errorString', 'peersConnected',
+          'peersGettingFromUs', 'peersSendingToUs', 'queuePosition'
+        ]
+      });
+
+      const torrents = response.data.arguments.torrents || [];
+      logToFile(`[Transmission:${this.name}] Retrieved ${torrents.length} torrents`);
+      
+      return torrents.map(torrent => this.normalizeDownload(torrent));
+    } catch (error) {
+      logToFile(`[Transmission:${this.name}] Error fetching torrents: ${error.message}`);
+      return [];
+    }
+  }
+
+  async getClientStatus() {
+    try {
+      const response = await this.makeRequest('session-get');
+      const sessionStats = await this.makeRequest('session-stats');
+      
+      return {
+        session: response.data.arguments,
+        stats: sessionStats.data.arguments
+      };
+    } catch (error) {
+      logToFile(`[Transmission:${this.name}] Error getting client status: ${error.message}`);
+      return null;
+    }
+  }
+
+  normalizeDownload(torrent) {
+    // Map Transmission status codes to normalized status
+    const statusMap = {
+      0: 'Stopped',      // TORRENT_STOPPED
+      1: 'Queued',       // TORRENT_CHECK_WAIT
+      2: 'Checking',     // TORRENT_CHECK
+      3: 'Queued',       // TORRENT_DOWNLOAD_WAIT
+      4: 'Downloading',  // TORRENT_DOWNLOAD
+      5: 'Queued',       // TORRENT_SEED_WAIT
+      6: 'Seeding',      // TORRENT_SEED
+      7: 'Unknown'       // TORRENT_IS_CHECKING (alias for 2)
+    };
+
+    const status = statusMap[torrent.status] || 'Unknown';
+
+    // Calculate progress and sizes
+    const progress = torrent.percentDone * 100;
+    const size = torrent.totalSize;
+    const downloaded = torrent.sizeWhenDone - torrent.leftUntilDone;
+
+    // Handle ETA - Transmission uses -1 for unknown, -2 for infinite
+    let eta = null;
+    if (torrent.eta >= 0) {
+      eta = torrent.eta;
+    }
+
+    // Extract category/labels
+    const labels = torrent.labels || [];
+    const category = labels.length > 0 ? labels[0] : undefined;
+
+    // Try to extract Sonarr/Radarr info from name
+    const arrInfo = this.extractArrInfo(torrent.name);
+
+    return {
+      id: torrent.hashString,
+      title: torrent.name,
+      type: 'torrent',
+      client: 'transmission',
+      instanceId: this.id,
+      instanceName: this.name,
+      status: status,
+      progress: Math.round(progress),
+      size: size,
+      downloaded: downloaded,
+      speed: torrent.rateDownload,
+      eta: eta,
+      category: category,
+      tags: labels,
+      savePath: torrent.downloadDir || undefined,
+      addedOn: torrent.addedDate ? new Date(torrent.addedDate * 1000).toISOString() : undefined,
+      arrQueueId: arrInfo.queueId,
+      arrType: arrInfo.type,
+      raw: torrent
+    };
+  }
+
+  extractArrInfo(filename) {
+    // Similar to SABnzbdClient, try to extract Sonarr/Radarr info
+    
+    // Look for patterns like "Series Name - S01E02 - Episode Title"
+    const seriesMatch = filename.match(/[-\s]S(\d{2})E(\d{2})/i);
+    if (seriesMatch) {
+      return { type: 'series' };
+    }
+
+    // Look for movie year patterns like "Movie Title (2023)"
+    const movieMatch = filename.match(/\((\d{4})\)/);
+    if (movieMatch && !seriesMatch) {
+      return { type: 'movie' };
+    }
+
+    return {};
+  }
+}
+
+module.exports = TransmissionClient;

server/index.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const express = require('express');
 const path = require('path');
 const cookieParser = require('cookie-parser');
@@ -5,7 +6,11 @@ const helmet = require('helmet');
 const rateLimit = require('express-rate-limit');
 const crypto = require('crypto');
 const fs = require('fs');
+const http = require('http');
+const https = require('https');
 require('dotenv').config();
+require('./utils/loadSecrets')();
+const { version } = require('../package.json');
 
 // Setup logging with levels
 // Levels: debug (0), info (1), warn (2), error (3), silent (4)
@@ -77,9 +82,11 @@ const sonarrRoutes = require('./routes/sonarr');
 const radarrRoutes = require('./routes/radarr');
 const embyRoutes = require('./routes/emby');
 const dashboardRoutes = require('./routes/dashboard');
+const historyRoutes = require('./routes/history');
 const authRoutes = require('./routes/auth');
 const verifyCsrf = require('./middleware/verifyCsrf');
 const { startPoller, POLL_INTERVAL, POLLING_ENABLED } = require('./utils/poller');
+const { validateInstanceUrl } = require('./utils/config');
 
 // ---------------------------------------------------------------------------
 // Startup environment validation
@@ -90,15 +97,23 @@ if (!cookieSecret && process.env.NODE_ENV === 'production') {
   process.exit(1);
 } else if (!cookieSecret) {
   console.warn('[Security] COOKIE_SECRET not set — unsigned cookies (dev only)');
+} else if (cookieSecret.length < 32) {
+  console.warn('[Security] COOKIE_SECRET is shorter than 32 characters — use openssl rand -hex 32');
 }
 if (!process.env.EMBY_URL && process.env.NODE_ENV === 'production') {
   console.error('[Config] EMBY_URL is required');
   process.exit(1);
 }
+if (process.env.EMBY_URL) {
+  validateInstanceUrl(process.env.EMBY_URL, 'EMBY_URL');
+}
 
 const app = express();
 const PORT = process.env.PORT || 3001;
 
+// Resolve TLS_ENABLED early — used in Helmet CSP and server startup
+const TLS_ENABLED = (process.env.TLS_ENABLED || 'true').toLowerCase() !== 'false';
+
 // ---------------------------------------------------------------------------
 // Trust proxy — required when behind Nginx/Caddy/Traefik so that
 // req.ip reflects the real client IP (not 127.0.0.1) and
@@ -137,7 +152,7 @@ app.use((req, res, next) => {
         baseUri: ["'self'"],
         frameAncestors: ["'none'"],
         formAction: ["'self'"],
-        upgradeInsecureRequests: process.env.NODE_ENV === 'production' ? [] : null
+        upgradeInsecureRequests: (process.env.TRUST_PROXY || TLS_ENABLED) ? [] : null
       }
     },
     hsts: {
@@ -182,7 +197,7 @@ app.use(express.json({ limit: '64kb' })); // prevent oversized JSON payloads
 // Used by Docker HEALTHCHECK and orchestrators.
 // ---------------------------------------------------------------------------
 app.get('/health', (req, res) => {
-  res.json({ status: 'ok', uptime: process.uptime() });
+  res.json({ status: 'ok', uptime: process.uptime(), version });
 });
 
 app.get('/ready', (req, res) => {
@@ -214,15 +229,17 @@ app.use(express.static(PUBLIC_DIR, {
   }
 }));
 
-// Serve index.html with nonce injected into the <script> and <link> tags
+// Serve index.html with CSP nonce injected into <script> tags
 function serveIndex(req, res) {
   fs.readFile(INDEX_HTML, 'utf8', (err, html) => {
     if (err) return res.status(500).send('Internal Server Error');
     const nonce = res.locals.cspNonce;
-    // Inject nonce into <script> and <link rel="stylesheet"> tags
+    // Only inject nonce into <script> tags — style-src 'self' already permits
+    // same-origin <link rel=stylesheet> without a nonce, and injecting a nonce
+    // onto <link> breaks mobile browsers / caching proxies (stale HTML carries
+    // the old nonce which no longer matches the per-request CSP header).
     const patched = html
-      .replace(/<script([^>]*)>/gi, `<script nonce="${nonce}"$1>`)
-      .replace(/<link([^>]*rel=["']stylesheet["'][^>]*)>/gi, `<link nonce="${nonce}"$1>`);
+      .replace(/<script([^>]*)>/gi, `<script nonce="${nonce}"$1>`);
     res.setHeader('Content-Type', 'text/html; charset=utf-8');
     res.send(patched);
   });
@@ -243,6 +260,7 @@ app.use('/api/sonarr', sonarrRoutes);
 app.use('/api/radarr', radarrRoutes);
 app.use('/api/emby', embyRoutes);
 app.use('/api/dashboard', dashboardRoutes);
+app.use('/api/history', historyRoutes);
 
 // SPA catch-all — serve index.html for any unmatched path
 app.get('*', serveIndex);
@@ -256,13 +274,79 @@ app.use((err, req, res, next) => {
   res.status(500).json({ error: 'Internal server error' });
 });
 
-app.listen(PORT, () => {
+// ---------------------------------------------------------------------------
+// TLS / HTTPS support
+// Set TLS_CERT and TLS_KEY to paths of your certificate and private key.
+// If unset, defaults to the bundled snakeoil self-signed certificate
+// (localhost/127.0.0.1 only — suitable for local testing).
+// Set TLS_ENABLED=false to force plain HTTP even if cert files exist.
+// ---------------------------------------------------------------------------
+const CERTS_DIR = path.join(__dirname, '../certs');
+const TLS_CERT_PATH = process.env.TLS_CERT || path.join(CERTS_DIR, 'snakeoil.crt');
+const TLS_KEY_PATH  = process.env.TLS_KEY  || path.join(CERTS_DIR, 'snakeoil.key');
+
+function loadTlsCredentials() {
+  if (!TLS_ENABLED) return null;
+  try {
+    return {
+      cert: fs.readFileSync(TLS_CERT_PATH),
+      key:  fs.readFileSync(TLS_KEY_PATH)
+    };
+  } catch (err) {
+    console.warn(`[TLS] Could not load certificate files — falling back to HTTP. (${err.message})`);
+    return null;
+  }
+}
+
+const tlsCredentials = loadTlsCredentials();
+const server = tlsCredentials
+  ? https.createServer(tlsCredentials, app)
+  : http.createServer(app);
+
+const protocol = tlsCredentials ? 'https' : 'http';
+const isSnakeoil = TLS_ENABLED &&
+  (!process.env.TLS_CERT || process.env.TLS_CERT === TLS_CERT_PATH);
+
+server.listen(PORT, () => {
   console.log(`=================================`);
-  console.log(`  sofarr - Your Downloads Dashboard`);
-  console.log(`  Server running on port ${PORT}`);
+  console.log(`  sofarr v${version} - Your Downloads Dashboard`);
+  console.log(`  Server running on ${protocol}://localhost:${PORT}`);
+  if (tlsCredentials && isSnakeoil) {
+    console.warn(`  [TLS] Using bundled snakeoil certificate (self-signed).`);
+    console.warn(`  [TLS] Set TLS_CERT and TLS_KEY for a trusted certificate.`);
+    console.warn(`  [TLS] Set TLS_ENABLED=false to disable TLS entirely.`);
+  } else if (tlsCredentials) {
+    console.log(`  [TLS] Certificate: ${TLS_CERT_PATH}`);
+  } else {
+    console.warn(`  [TLS] Running in plain HTTP mode — not suitable for production.`);
+  }
   console.log(`  Log level: ${process.env.LOG_LEVEL || 'info'}`);
   console.log(`  Polling: ${POLLING_ENABLED ? POLL_INTERVAL + 'ms' : 'disabled (on-demand)'}`);
   console.log(`  Trust proxy: ${process.env.TRUST_PROXY || 'disabled'}`);
   console.log(`=================================`);
   startPoller();
 });
+
+// ---------------------------------------------------------------------------
+// Graceful shutdown — handle SIGTERM (Docker stop) and SIGINT (Ctrl+C)
+// Stop the poller, close the HTTP server (stops accepting new connections),
+// then let Node drain existing keep-alive connections and exit cleanly.
+// ---------------------------------------------------------------------------
+const { stopPoller } = require('./utils/poller');
+
+function shutdown(signal) {
+  console.log(`[Server] ${signal} received — shutting down gracefully`);
+  stopPoller();
+  server.close(() => {
+    console.log('[Server] HTTP server closed');
+    process.exit(0);
+  });
+  // Force exit after 10 s if connections don't drain
+  setTimeout(() => {
+    console.error('[Server] Forced exit after 10 s timeout');
+    process.exit(1);
+  }, 10000).unref();
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT',  () => shutdown('SIGINT'));

server/middleware/requireAuth.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 function requireAuth(req, res, next) {
   const signed = !!process.env.COOKIE_SECRET;
   const raw = signed ? req.signedCookies.emby_user : req.cookies.emby_user;

server/middleware/verifyCsrf.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * CSRF protection using the double-submit cookie pattern.
  *

server/routes/auth.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const express = require('express');
 const axios = require('axios');
 const crypto = require('crypto');
@@ -70,13 +71,15 @@ router.post('/login', loginLimiter, async (req, res) => {
     // Set authentication cookie (signed when COOKIE_SECRET is set).
     // rememberMe=true  → persistent cookie, expires in 30 days
     // rememberMe=false → session cookie, expires when browser closes
-    // secure is always true — the app should sit behind HTTPS in production;
-    // behind a reverse proxy set TRUST_PROXY=1 so req.secure works correctly.
+    // secure:true only when TRUST_PROXY is set — i.e. a TLS-terminating reverse
+    // proxy is in front. Without it the app may be accessed over plain HTTP and
+    // secure cookies would never be sent back by the browser.
     const cookiePayload = JSON.stringify({ id: user.Id, name: user.Name, isAdmin });
     const signed = !!process.env.COOKIE_SECRET;
+    const secureCookie = !!process.env.TRUST_PROXY; // only send over HTTPS when behind a TLS proxy
     const cookieOptions = {
       httpOnly: true,
-      secure: process.env.NODE_ENV === 'production',
+      secure: secureCookie,
       sameSite: 'strict',
       signed,
       path: '/'
@@ -91,7 +94,7 @@ router.post('/login', loginLimiter, async (req, res) => {
     const csrfToken = crypto.randomBytes(32).toString('hex');
     res.cookie('csrf_token', csrfToken, {
       httpOnly: false, // intentionally readable by JS for the double-submit pattern
-      secure: process.env.NODE_ENV === 'production',
+      secure: secureCookie,
       sameSite: 'strict',
       path: '/'
     });
@@ -142,7 +145,7 @@ router.get('/csrf', (req, res) => {
   const csrfToken = crypto.randomBytes(32).toString('hex');
   res.cookie('csrf_token', csrfToken, {
     httpOnly: false,
-    secure: process.env.NODE_ENV === 'production',
+    secure: !!process.env.TRUST_PROXY,
     sameSite: 'strict',
     path: '/'
   });
@@ -168,14 +171,14 @@ router.post('/logout', async (req, res) => {
   }
   res.clearCookie('emby_user', {
     httpOnly: true,
-    secure: process.env.NODE_ENV === 'production',
+    secure: !!process.env.TRUST_PROXY,
     sameSite: 'strict',
     signed: !!process.env.COOKIE_SECRET,
     path: '/'
   });
   res.clearCookie('csrf_token', {
     httpOnly: false,
-    secure: process.env.NODE_ENV === 'production',
+    secure: !!process.env.TRUST_PROXY,
     sameSite: 'strict',
     path: '/'
   });

server/routes/dashboard.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const express = require('express');
 const router = express.Router();
 const requireAuth = require('../middleware/requireAuth');
@@ -94,6 +95,56 @@ function getRadarrLink(movie) {
   return `${movie._instanceUrl}/movie/${movie.titleSlug}`;
 }
 
+// Determine if a download can be blocklisted by the current user
+// Admins: always true (they have arrQueueId)
+// Non-admins: true if importIssues OR (torrent >1h old AND availability<100%)
+function canBlocklist(download, isAdmin) {
+  if (isAdmin) return true;
+  if (download.importIssues && download.importIssues.length > 0) return true;
+  if (download.qbittorrent && download.addedOn && download.availability) {
+    const oneHourAgo = Date.now() - 3600000; // 1 hour in ms
+    const addedOn = new Date(download.addedOn).getTime();
+    const isOldEnough = addedOn < oneHourAgo;
+    const availability = parseFloat(download.availability);
+    const isLowAvailability = availability < 100;
+    return isOldEnough && isLowAvailability;
+  }
+  return false;
+}
+
+// Extract episode info from a Sonarr queue/history record.
+// Returns { season, episode, title } or null if data is missing.
+function extractEpisode(record) {
+  const ep = record.episode || {};
+  const s = ep.seasonNumber != null ? ep.seasonNumber : record.seasonNumber;
+  const e = ep.episodeNumber != null ? ep.episodeNumber : record.episodeNumber;
+  if (s == null || e == null) return null;
+  const title = ep.title || null;
+  return { season: s, episode: e, title };
+}
+
+// Find all episodes associated with a download by matching all queue/history records
+// that share the same title string.  Returns sorted array of { season, episode, title }.
+function gatherEpisodes(titleLower, sonarrRecords) {
+  const episodes = [];
+  const seen = new Set();
+  for (const r of sonarrRecords) {
+    const rTitle = (r.title || r.sourceTitle || '').toLowerCase();
+    if (rTitle && (rTitle.includes(titleLower) || titleLower.includes(rTitle))) {
+      const ep = extractEpisode(r);
+      if (ep) {
+        const key = `${ep.season}x${ep.episode}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          episodes.push(ep);
+        }
+      }
+    }
+  }
+  episodes.sort((a, b) => a.season - b.season || a.episode - b.episode);
+  return episodes;
+}
+
 // Fetch all Emby users and return a Map<lowerName -> displayName> (and sanitized variants).
 // Result is cached for 60s to avoid hammering Emby on every dashboard poll.
 async function getEmbyUsers() {
@@ -277,7 +328,7 @@ router.get('/user-downloads', requireAuth, async (req, res) => {
                   speed: slotState.speed,
                   eta: slot.timeleft,
                   seriesName: series.title,
-                  episodeInfo: sonarrMatch,
+                  episodes: gatherEpisodes(nzbNameLower, sonarrQueue.data.records),
                   allTags,
                   matchedUserTag: matchedUserTag || null,
                   tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined
@@ -288,7 +339,14 @@ router.get('/user-downloads', requireAuth, async (req, res) => {
                   dlObj.downloadPath = slot.storage || null;
                   dlObj.targetPath = series.path || null;
                   dlObj.arrLink = getSonarrLink(series);
+                  dlObj.arrQueueId = sonarrMatch.id;
+                  dlObj.arrType = 'sonarr';
+                  dlObj.arrInstanceUrl = sonarrMatch._instanceUrl || null;
+                  dlObj.arrInstanceKey = sonarrMatch._instanceKey || null;
+                  dlObj.arrContentId = sonarrMatch.episodeId || null;
+                  dlObj.arrContentType = 'episode';
                 }
+                dlObj.canBlocklist = canBlocklist(dlObj, isAdmin);
                 userDownloads.push(dlObj);
               }
             }
@@ -330,7 +388,14 @@ router.get('/user-downloads', requireAuth, async (req, res) => {
                   dlObj.downloadPath = slot.storage || null;
                   dlObj.targetPath = movie.path || null;
                   dlObj.arrLink = getRadarrLink(movie);
+                  dlObj.arrQueueId = radarrMatch.id;
+                  dlObj.arrType = 'radarr';
+                  dlObj.arrInstanceUrl = radarrMatch._instanceUrl || null;
+                  dlObj.arrInstanceKey = radarrMatch._instanceKey || null;
+                  dlObj.arrContentId = radarrMatch.movieId || null;
+                  dlObj.arrContentType = 'movie';
                 }
+                dlObj.canBlocklist = canBlocklist(dlObj, isAdmin);
                 userDownloads.push(dlObj);
               }
             }
@@ -374,7 +439,7 @@ router.get('/user-downloads', requireAuth, async (req, res) => {
                   size: slot.size,
                   completedAt: slot.completed_time,
                   seriesName: series.title,
-                  episodeInfo: sonarrMatch,
+                  episodes: gatherEpisodes(nzbNameLower, sonarrHistory.data.records),
                   allTags,
                   matchedUserTag: matchedUserTag || null,
                   tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined
@@ -477,7 +542,7 @@ router.get('/user-downloads', requireAuth, async (req, res) => {
               download.type = 'series';
               download.coverArt = getCoverArt(series);
               download.seriesName = series.title;
-              download.episodeInfo = sonarrMatch;
+              download.episodes = gatherEpisodes(torrentNameLower, sonarrQueue.data.records);
               download.allTags = allTags;
               download.matchedUserTag = matchedUserTag || null;
               download.tagBadges = showAll ? buildTagBadges(allTags, embyUserMap) : undefined;
@@ -487,7 +552,14 @@ router.get('/user-downloads', requireAuth, async (req, res) => {
                 download.downloadPath = download.savePath || null;
                 download.targetPath = series.path || null;
                 download.arrLink = getSonarrLink(series);
+                download.arrQueueId = sonarrMatch.id;
+                download.arrType = 'sonarr';
+                download.arrInstanceUrl = sonarrMatch._instanceUrl || null;
+                download.arrInstanceKey = sonarrMatch._instanceKey || null;
+                download.arrContentId = sonarrMatch.episodeId || null;
+                download.arrContentType = 'episode';
               }
+              download.canBlocklist = canBlocklist(download, isAdmin);
               userDownloads.push(download);
               continue; // Skip to next torrent
             }
@@ -522,7 +594,14 @@ router.get('/user-downloads', requireAuth, async (req, res) => {
                 download.downloadPath = download.savePath || null;
                 download.targetPath = movie.path || null;
                 download.arrLink = getRadarrLink(movie);
+                download.arrQueueId = radarrMatch.id;
+                download.arrType = 'radarr';
+                download.arrInstanceUrl = radarrMatch._instanceUrl || null;
+                download.arrInstanceKey = radarrMatch._instanceKey || null;
+                download.arrContentId = radarrMatch.movieId || null;
+                download.arrContentType = 'movie';
               }
+              download.canBlocklist = canBlocklist(download, isAdmin);
               userDownloads.push(download);
               continue; // Skip to next torrent
             }
@@ -547,7 +626,7 @@ router.get('/user-downloads', requireAuth, async (req, res) => {
               download.type = 'series';
               download.coverArt = getCoverArt(series);
               download.seriesName = series.title;
-              download.episodeInfo = sonarrHistoryMatch;
+              download.episodes = gatherEpisodes(torrentNameLower, sonarrHistory.data.records);
               download.allTags = allTags;
               download.matchedUserTag = matchedUserTag || null;
               download.tagBadges = showAll ? buildTagBadges(allTags, embyUserMap) : undefined;
@@ -857,10 +936,11 @@ router.get('/stream', requireAuth, async (req, res) => {
               const allTags = extractAllTags(series.tags, sonarrTagMap);
               const matchedUserTag = extractUserTag(series.tags, sonarrTagMap, username);
               if (showAll ? allTags.length > 0 : !!matchedUserTag) {
-                const dlObj = { type: 'series', title: nzbName, coverArt: getCoverArt(series), status: slotState.status, progress: slot.percentage, mb: slot.mb, mbmissing: slot.mbmissing, size: slot.size, speed: slotState.speed, eta: slot.timeleft, seriesName: series.title, episodeInfo: sonarrMatch, allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined };
+                const dlObj = { type: 'series', title: nzbName, coverArt: getCoverArt(series), status: slotState.status, progress: slot.percentage, mb: slot.mb, mbmissing: slot.mbmissing, size: slot.size, speed: slotState.speed, eta: slot.timeleft, seriesName: series.title, episodes: gatherEpisodes(nzbNameLower, sonarrQueue.data.records), allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined };
                 const issues = getImportIssues(sonarrMatch);
                 if (issues) dlObj.importIssues = issues;
-                if (isAdmin) { dlObj.downloadPath = slot.storage || null; dlObj.targetPath = series.path || null; dlObj.arrLink = getSonarrLink(series); }
+                if (isAdmin) { dlObj.downloadPath = slot.storage || null; dlObj.targetPath = series.path || null; dlObj.arrLink = getSonarrLink(series); dlObj.arrQueueId = sonarrMatch.id; dlObj.arrType = 'sonarr'; dlObj.arrInstanceUrl = sonarrMatch._instanceUrl || null; dlObj.arrInstanceKey = sonarrMatch._instanceKey || null; dlObj.arrContentId = sonarrMatch.episodeId || null; dlObj.arrContentType = 'episode'; }
+                dlObj.canBlocklist = canBlocklist(dlObj, isAdmin);
                 userDownloads.push(dlObj);
               }
             }
@@ -879,7 +959,8 @@ router.get('/stream', requireAuth, async (req, res) => {
                 const dlObj = { type: 'movie', title: nzbName, coverArt: getCoverArt(movie), status: slotState.status, progress: slot.percentage, mb: slot.mb, mbmissing: slot.mbmissing, size: slot.size, speed: slotState.speed, eta: slot.timeleft, movieName: movie.title, movieInfo: radarrMatch, allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined };
                 const issues = getImportIssues(radarrMatch);
                 if (issues) dlObj.importIssues = issues;
-                if (isAdmin) { dlObj.downloadPath = slot.storage || null; dlObj.targetPath = movie.path || null; dlObj.arrLink = getRadarrLink(movie); }
+                if (isAdmin) { dlObj.downloadPath = slot.storage || null; dlObj.targetPath = movie.path || null; dlObj.arrLink = getRadarrLink(movie); dlObj.arrQueueId = radarrMatch.id; dlObj.arrType = 'radarr'; dlObj.arrInstanceUrl = radarrMatch._instanceUrl || null; dlObj.arrInstanceKey = radarrMatch._instanceKey || null; dlObj.arrContentId = radarrMatch.movieId || null; dlObj.arrContentType = 'movie'; }
+                dlObj.canBlocklist = canBlocklist(dlObj, isAdmin);
                 userDownloads.push(dlObj);
               }
             }
@@ -904,7 +985,7 @@ router.get('/stream', requireAuth, async (req, res) => {
               const allTags = extractAllTags(series.tags, sonarrTagMap);
               const matchedUserTag = extractUserTag(series.tags, sonarrTagMap, username);
               if (showAll ? allTags.length > 0 : !!matchedUserTag) {
-                const dlObj = { type: 'series', title: nzbName, coverArt: getCoverArt(series), status: slot.status, size: slot.size, completedAt: slot.completed_time, seriesName: series.title, episodeInfo: sonarrMatch, allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined };
+                const dlObj = { type: 'series', title: nzbName, coverArt: getCoverArt(series), status: slot.status, size: slot.size, completedAt: slot.completed_time, seriesName: series.title, episodes: gatherEpisodes(nzbNameLower, sonarrHistory.data.records), allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined };
                 if (isAdmin) { dlObj.downloadPath = slot.storage || null; dlObj.targetPath = series.path || null; dlObj.arrLink = getSonarrLink(series); }
                 userDownloads.push(dlObj);
               }
@@ -944,9 +1025,10 @@ router.get('/stream', requireAuth, async (req, res) => {
             const matchedUserTag = extractUserTag(series.tags, sonarrTagMap, username);
             if (showAll ? allTags.length > 0 : !!matchedUserTag) {
               const download = mapTorrentToDownload(torrent);
-              Object.assign(download, { type: 'series', coverArt: getCoverArt(series), seriesName: series.title, episodeInfo: sonarrMatch, allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined });
+              Object.assign(download, { type: 'series', coverArt: getCoverArt(series), seriesName: series.title, episodes: gatherEpisodes(torrentNameLower, sonarrQueue.data.records), allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined });
               const issues = getImportIssues(sonarrMatch); if (issues) download.importIssues = issues;
-              if (isAdmin) { download.downloadPath = download.savePath || null; download.targetPath = series.path || null; download.arrLink = getSonarrLink(series); }
+              if (isAdmin) { download.downloadPath = download.savePath || null; download.targetPath = series.path || null; download.arrLink = getSonarrLink(series); download.arrQueueId = sonarrMatch.id; download.arrType = 'sonarr'; download.arrInstanceUrl = sonarrMatch._instanceUrl || null; download.arrInstanceKey = sonarrMatch._instanceKey || null; download.arrContentId = sonarrMatch.episodeId || null; download.arrContentType = 'episode'; }
+              download.canBlocklist = canBlocklist(download, isAdmin);
               userDownloads.push(download); continue;
             }
           }
@@ -962,7 +1044,8 @@ router.get('/stream', requireAuth, async (req, res) => {
               const download = mapTorrentToDownload(torrent);
               Object.assign(download, { type: 'movie', coverArt: getCoverArt(movie), movieName: movie.title, movieInfo: radarrMatch, allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined });
               const issues = getImportIssues(radarrMatch); if (issues) download.importIssues = issues;
-              if (isAdmin) { download.downloadPath = download.savePath || null; download.targetPath = movie.path || null; download.arrLink = getRadarrLink(movie); }
+              if (isAdmin) { download.downloadPath = download.savePath || null; download.targetPath = movie.path || null; download.arrLink = getRadarrLink(movie); download.arrQueueId = radarrMatch.id; download.arrType = 'radarr'; download.arrInstanceUrl = radarrMatch._instanceUrl || null; download.arrInstanceKey = radarrMatch._instanceKey || null; download.arrContentId = radarrMatch.movieId || null; download.arrContentType = 'movie'; }
+              download.canBlocklist = canBlocklist(download, isAdmin);
               userDownloads.push(download); continue;
             }
           }
@@ -976,7 +1059,7 @@ router.get('/stream', requireAuth, async (req, res) => {
             const matchedUserTag = extractUserTag(series.tags, sonarrTagMap, username);
             if (showAll ? allTags.length > 0 : !!matchedUserTag) {
               const download = mapTorrentToDownload(torrent);
-              Object.assign(download, { type: 'series', coverArt: getCoverArt(series), seriesName: series.title, episodeInfo: sonarrHistoryMatch, allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined });
+              Object.assign(download, { type: 'series', coverArt: getCoverArt(series), seriesName: series.title, episodes: gatherEpisodes(torrentNameLower, sonarrHistory.data.records), allTags, matchedUserTag: matchedUserTag || null, tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined });
               if (isAdmin) { download.downloadPath = download.savePath || null; download.targetPath = series.path || null; download.arrLink = getSonarrLink(series); }
               userDownloads.push(download); continue;
             }
@@ -1026,4 +1109,68 @@ router.get('/stream', requireAuth, async (req, res) => {
   });
 });
 
+/**
+ * POST /api/dashboard/blocklist-search
+ *
+ * Admin-only. Removes a queue item from Sonarr/Radarr with blocklist=true
+ * (so the release is not grabbed again), then immediately triggers a new
+ * automatic search for the same episode/movie.
+ *
+ * Body: {
+ *   arrQueueId:    number   — Sonarr/Radarr queue record id
+ *   arrType:       'sonarr'|'radarr'
+ *   arrInstanceUrl: string  — base URL of the arr instance
+ *   arrInstanceKey: string  — API key for the arr instance
+ *   arrContentId:  number   — episodeId (Sonarr) or movieId (Radarr)
+ *   arrContentType: 'episode'|'movie'
+ * }
+ */
+router.post('/blocklist-search', requireAuth, async (req, res) => {
+  try {
+    const user = req.user;
+    if (!user.isAdmin) {
+      return res.status(403).json({ error: 'Admin access required' });
+    }
+
+    const { arrQueueId, arrType, arrInstanceUrl, arrInstanceKey, arrContentId, arrContentType } = req.body;
+
+    if (!arrQueueId || !arrType || !arrInstanceUrl || !arrInstanceKey || !arrContentId || !arrContentType) {
+      return res.status(400).json({ error: 'Missing required fields' });
+    }
+    if (arrType !== 'sonarr' && arrType !== 'radarr') {
+      return res.status(400).json({ error: 'arrType must be sonarr or radarr' });
+    }
+
+    const headers = { 'X-Api-Key': arrInstanceKey };
+
+    // Step 1: Remove from queue with blocklist=true
+    await axios.delete(`${arrInstanceUrl}/api/v3/queue/${arrQueueId}`, {
+      headers,
+      params: { removeFromClient: true, blocklist: true }
+    });
+
+    // Step 2: Trigger a new automatic search
+    let commandBody;
+    if (arrType === 'sonarr' && arrContentType === 'episode') {
+      commandBody = { name: 'EpisodeSearch', episodeIds: [arrContentId] };
+    } else if (arrType === 'radarr' && arrContentType === 'movie') {
+      commandBody = { name: 'MoviesSearch', movieIds: [arrContentId] };
+    }
+
+    if (commandBody) {
+      await axios.post(`${arrInstanceUrl}/api/v3/command`, commandBody, { headers });
+    }
+
+    // Invalidate the poll cache so the next SSE push reflects the removed item
+    const { pollAllServices } = require('../utils/poller');
+    pollAllServices().catch(() => {});
+
+    console.log(`[Dashboard] Blocklist+search: ${arrType} queueId=${arrQueueId} contentId=${arrContentId} by ${user.name}`);
+    res.json({ ok: true });
+  } catch (err) {
+    console.error('[Dashboard] blocklist-search error:', sanitizeError(err));
+    res.status(502).json({ error: 'Failed to blocklist and search', details: sanitizeError(err) });
+  }
+});
+
 module.exports = router;

server/routes/emby.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const express = require('express');
 const axios = require('axios');
 const router = express.Router();

server/routes/history.js

@@ -0,0 +1,386 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const express = require('express');
+const router = express.Router();
+const axios = require('axios');
+const requireAuth = require('../middleware/requireAuth');
+const cache = require('../utils/cache');
+const { fetchSonarrHistory, fetchRadarrHistory, classifySonarrEvent, classifyRadarrEvent } = require('../utils/historyFetcher');
+const { getSonarrInstances, getRadarrInstances } = require('../utils/config');
+const sanitizeError = require('../utils/sanitizeError');
+
+// Re-use the same tag/cover-art helpers as dashboard.js by importing them
+// from a shared location.  For now they are inlined here to keep dashboard.js
+// untouched (zero-conflict v1 merges).  If these diverge they can be extracted
+// into server/utils/dashboardHelpers.js in a later refactor.
+
+function getCoverArt(item) {
+  if (!item || !item.images) return null;
+  const poster = item.images.find(img => img.coverType === 'poster');
+  if (poster) return poster.remoteUrl || poster.url || null;
+  const fanart = item.images.find(img => img.coverType === 'fanart');
+  return fanart ? (fanart.remoteUrl || fanart.url || null) : null;
+}
+
+function sanitizeTagLabel(input) {
+  if (!input) return '';
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+
+function tagMatchesUser(tag, username) {
+  if (!tag || !username) return false;
+  const tagLower = tag.toLowerCase();
+  if (tagLower === username) return true;
+  if (tagLower === sanitizeTagLabel(username)) return true;
+  return false;
+}
+
+function extractAllTags(tags, tagMap) {
+  if (!tags || tags.length === 0) return [];
+  if (tagMap) return tags.map(id => tagMap.get(id)).filter(Boolean);
+  return tags.map(t => t && t.label).filter(Boolean);
+}
+
+function extractUserTag(tags, tagMap, username) {
+  const allLabels = extractAllTags(tags, tagMap);
+  if (!allLabels.length) return null;
+  if (username) {
+    const match = allLabels.find(label => tagMatchesUser(label, username));
+    if (match) return match;
+  }
+  return null;
+}
+
+async function getEmbyUsers() {
+  const cached = cache.get('emby:users');
+  if (cached) return cached;
+  try {
+    const embyUrl = process.env.EMBY_URL;
+    const embyKey = process.env.EMBY_API_KEY;
+    if (!embyUrl || !embyKey) return new Map();
+    const res = await axios.get(`${embyUrl}/Users`, { params: { api_key: embyKey } });
+    const users = res.data || [];
+    const map = new Map();
+    for (const u of users) {
+      if (!u.Name) continue;
+      const lower = u.Name.toLowerCase();
+      map.set(lower, u.Name);
+      map.set(sanitizeTagLabel(lower), u.Name);
+    }
+    cache.set('emby:users', map, 60000);
+    return map;
+  } catch (err) {
+    console.error('[History] Failed to fetch Emby users:', err.message);
+    return new Map();
+  }
+}
+
+function buildTagBadges(allTags, embyUserMap) {
+  return allTags.map(label => {
+    const lower = label.toLowerCase();
+    const sanitized = sanitizeTagLabel(label);
+    const matchedUser = embyUserMap.get(lower) || embyUserMap.get(sanitized) || null;
+    return { label, matchedUser };
+  });
+}
+
+// Extract episode info from a Sonarr history record.
+function extractEpisode(record) {
+  const ep = record.episode || {};
+  const s = ep.seasonNumber != null ? ep.seasonNumber : record.seasonNumber;
+  const e = ep.episodeNumber != null ? ep.episodeNumber : record.episodeNumber;
+  if (s == null || e == null) return null;
+  const title = ep.title || null;
+  return { season: s, episode: e, title };
+}
+
+// Find all episodes associated with a download by matching all history records
+// that share the same source title.  Returns sorted, deduplicated array.
+function gatherEpisodes(titleLower, records) {
+  const episodes = [];
+  const seen = new Set();
+  for (const r of records) {
+    const rTitle = (r.sourceTitle || r.title || '').toLowerCase();
+    if (rTitle && (rTitle.includes(titleLower) || titleLower.includes(rTitle))) {
+      const ep = extractEpisode(r);
+      if (ep) {
+        const key = `${ep.season}x${ep.episode}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          episodes.push(ep);
+        }
+      }
+    }
+  }
+  episodes.sort((a, b) => a.season - b.season || a.episode - b.episode);
+  return episodes;
+}
+
+/**
+ * Deduplicate history items so that for each unique content item (episode or
+ * movie) only the most-recent record is shown, with the following rules:
+ *
+ *  - If the most recent event is 'imported'  → show it; suppress older failures.
+ *  - If the most recent event is 'failed' and the item currently has a file
+ *    (hasFile = true) → show the failure but flag it as availableForUpgrade:true
+ *    so the UI can indicate the item is available but an upgrade is in progress.
+ *  - If the most recent event is 'failed' and hasFile is false → show normally.
+ *
+ * Items are keyed by: type + instanceName + contentId (episodeId or movieId).
+ * Records without a contentId fall through unchanged (no deduplication possible).
+ *
+ * @param {Array} items - Already-built history items (unsorted)
+ * @param {Array} sonarrRaw - Raw Sonarr records (for hasFile lookup)
+ * @param {Array} radarrRaw - Raw Radarr records (for hasFile lookup)
+ * @returns {Array}
+ */
+function deduplicateHistoryItems(items, sonarrRaw, radarrRaw) {
+  // Build hasFile lookup: contentId → boolean
+  const sonarrHasFile = new Map();
+  for (const r of sonarrRaw) {
+    const id = r.episodeId;
+    if (id != null) {
+      const hf = r.episode && r.episode.hasFile != null ? r.episode.hasFile : undefined;
+      if (hf !== undefined && !sonarrHasFile.has(id)) sonarrHasFile.set(id, hf);
+    }
+  }
+  const radarrHasFile = new Map();
+  for (const r of radarrRaw) {
+    const id = r.movieId;
+    if (id != null) {
+      const hf = r.movie && r.movie.hasFile != null ? r.movie.hasFile : undefined;
+      if (hf !== undefined && !radarrHasFile.has(id)) radarrHasFile.set(id, hf);
+    }
+  }
+
+  // Group items by dedup key; preserve insertion order (newest first from caller)
+  const groups = new Map();
+  const noKey = [];
+  for (const item of items) {
+    const cid = item._contentId;
+    if (cid == null) { noKey.push(item); continue; }
+    const key = `${item.type}|${item.instanceName}|${cid}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(item);
+  }
+
+  const result = [...noKey];
+  for (const [, group] of groups) {
+    // group[0] is the most recent (items are pushed in date-descending order)
+    const best = group[0];
+    if (best.outcome === 'imported') {
+      result.push(best);
+      continue;
+    }
+    if (best.outcome === 'failed') {
+      const hasFile = best.type === 'series'
+        ? sonarrHasFile.get(best._contentId)
+        : radarrHasFile.get(best._contentId);
+      if (hasFile) best.availableForUpgrade = true;
+      result.push(best);
+      continue;
+    }
+    result.push(best);
+  }
+  return result;
+}
+
+function getSonarrLink(series) {
+  if (!series || !series._instanceUrl || !series.titleSlug) return null;
+  return `${series._instanceUrl}/series/${series.titleSlug}`;
+}
+
+function getRadarrLink(movie) {
+  if (!movie || !movie._instanceUrl || !movie.titleSlug) return null;
+  return `${movie._instanceUrl}/movie/${movie.titleSlug}`;
+}
+
+/**
+ * GET /api/history/recent
+ *
+ * Returns Sonarr/Radarr history records (imported + failed) for the
+ * authenticated user, filtered to the last RECENT_COMPLETED_DAYS days
+ * (default 7, overridable via env or ?days= query param).
+ *
+ * Response shape:
+ * {
+ *   user: string,
+ *   isAdmin: boolean,
+ *   days: number,
+ *   history: HistoryItem[]
+ * }
+ *
+ * HistoryItem shape:
+ * {
+ *   type: 'series'|'movie',
+ *   outcome: 'imported'|'failed',
+ *   title: string,            // sourceTitle from arr record
+ *   seriesName?: string,      // series.title (Sonarr)
+ *   movieName?: string,       // movie.title (Radarr)
+ *   coverArt: string|null,
+ *   completedAt: string,      // ISO date string from arr record
+ *   quality: string|null,
+ *   instanceName: string,     // arr instance name
+ *   arrLink: string|null,     // link to item in Sonarr/Radarr UI
+ *   allTags: string[],
+ *   matchedUserTag: string|null,
+ *   // admin-only:
+ *   arrRecordId?: number,
+ *   failureMessage?: string,
+ * }
+ */
+router.get('/recent', requireAuth, async (req, res) => {
+  try {
+    const user = req.user;
+    const username = user.name.toLowerCase();
+    const isAdmin = !!user.isAdmin;
+    const showAll = isAdmin && req.query.showAll === 'true';
+
+    const defaultDays = parseInt(process.env.RECENT_COMPLETED_DAYS, 10) || 7;
+    const requestedDays = parseInt(req.query.days, 10);
+    const days = (requestedDays > 0 && requestedDays <= 90) ? requestedDays : defaultDays;
+
+    const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+    // Fetch tag maps and history in parallel
+    const sonarrInstances = getSonarrInstances();
+    const radarrInstances = getRadarrInstances();
+
+    const [sonarrHistory, radarrHistory, embyUserMap] = await Promise.all([
+      fetchSonarrHistory(since),
+      fetchRadarrHistory(since),
+      showAll ? getEmbyUsers() : Promise.resolve(new Map())
+    ]);
+
+    // Build tag maps from the cached poll data where available,
+    // falling back to what's embedded in history records
+    const sonarrTagsData = cache.get('poll:sonarr-tags') || [];
+    const radarrTagsData = cache.get('poll:radarr-tags') || [];
+    const sonarrTagMap = new Map(sonarrTagsData.flatMap(t => t.data || []).map(t => [t.id, t.label]));
+    const radarrTagMap = new Map(radarrTagsData.map(t => [t.id, t.label]));
+
+    const historyItems = [];
+
+    // --- Sonarr history ---
+    for (const record of sonarrHistory) {
+      try {
+        const outcome = classifySonarrEvent(record.eventType);
+        if (outcome === 'other') continue;
+
+        const series = record.series;
+        if (!series) continue;
+
+        const allTags = extractAllTags(series.tags, sonarrTagMap);
+        const matchedUserTag = extractUserTag(series.tags, sonarrTagMap, username);
+        const hasAnyTag = allTags.length > 0;
+
+        if (!(showAll ? hasAnyTag : !!matchedUserTag)) continue;
+
+        const quality = record.quality && record.quality.quality && record.quality.quality.name
+          ? record.quality.quality.name
+          : null;
+
+        const sourceTitle = record.sourceTitle || record.title || series.title;
+        const item = {
+          type: 'series',
+          outcome,
+          title: sourceTitle,
+          seriesName: series.title,
+          episodes: gatherEpisodes(sourceTitle.toLowerCase(), sonarrHistory),
+          coverArt: getCoverArt(series),
+          completedAt: record.date,
+          quality,
+          instanceName: record._instanceName || null,
+          arrLink: getSonarrLink(series),
+          allTags,
+          matchedUserTag: matchedUserTag || null,
+          tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined,
+          _contentId: record.episodeId != null ? record.episodeId : null
+        };
+
+        if (isAdmin) {
+          item.arrRecordId = record.id;
+          if (outcome === 'failed' && record.data && record.data.message) {
+            item.failureMessage = record.data.message;
+          }
+        }
+
+        historyItems.push(item);
+      } catch (err) {
+        console.error('[History] Error processing Sonarr record:', err.message);
+      }
+    }
+
+    // --- Radarr history ---
+    for (const record of radarrHistory) {
+      try {
+        const outcome = classifyRadarrEvent(record.eventType);
+        if (outcome === 'other') continue;
+
+        const movie = record.movie;
+        if (!movie) continue;
+
+        const allTags = extractAllTags(movie.tags, radarrTagMap);
+        const matchedUserTag = extractUserTag(movie.tags, radarrTagMap, username);
+        const hasAnyTag = allTags.length > 0;
+
+        if (!(showAll ? hasAnyTag : !!matchedUserTag)) continue;
+
+        const quality = record.quality && record.quality.quality && record.quality.quality.name
+          ? record.quality.quality.name
+          : null;
+
+        const item = {
+          type: 'movie',
+          outcome,
+          title: record.sourceTitle || record.title || movie.title,
+          movieName: movie.title,
+          coverArt: getCoverArt(movie),
+          completedAt: record.date,
+          quality,
+          instanceName: record._instanceName || null,
+          arrLink: getRadarrLink(movie),
+          allTags,
+          matchedUserTag: matchedUserTag || null,
+          tagBadges: showAll ? buildTagBadges(allTags, embyUserMap) : undefined,
+          _contentId: record.movieId != null ? record.movieId : null
+        };
+
+        if (isAdmin) {
+          item.arrRecordId = record.id;
+          if (outcome === 'failed' && record.data && record.data.message) {
+            item.failureMessage = record.data.message;
+          }
+        }
+
+        historyItems.push(item);
+      } catch (err) {
+        console.error('[History] Error processing Radarr record:', err.message);
+      }
+    }
+
+    // Deduplicate: for each content item keep only the most-recent record,
+    // suppressing failures that were superseded by a successful import.
+    // Must run before sort so insertion order (newest-first from arr API) is preserved.
+    const dedupedItems = deduplicateHistoryItems(historyItems, sonarrHistory, radarrHistory);
+
+    // Strip internal dedup key before sending to client
+    for (const item of dedupedItems) delete item._contentId;
+
+    // Sort newest first
+    dedupedItems.sort((a, b) => new Date(b.completedAt) - new Date(a.completedAt));
+
+    console.log(`[History] Returning ${dedupedItems.length} items for user ${user.name} (days=${days}, showAll=${showAll})`);
+
+    res.json({
+      user: user.name,
+      isAdmin,
+      days,
+      history: dedupedItems
+    });
+  } catch (err) {
+    console.error('[History] Error:', err.message);
+    res.status(500).json({ error: 'Failed to fetch history', details: sanitizeError(err) });
+  }
+});
+
+module.exports = router;

server/routes/radarr.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const express = require('express');
 const axios = require('axios');
 const router = express.Router();

server/routes/sabnzbd.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const express = require('express');
 const axios = require('axios');
 const router = express.Router();

server/routes/sonarr.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const express = require('express');
 const axios = require('axios');
 const router = express.Router();

server/utils/cache.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const { logToFile } = require('./logger');
 
 class MemoryCache {

server/utils/config.js

@@ -1,5 +1,28 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const { logToFile } = require('./logger');
 
+// Validate that a configured service URL is well-formed and uses http(s).
+// Emits a warning (never throws) so a misconfigured instance degrades
+// gracefully rather than crashing the whole server.
+function validateInstanceUrl(url, instanceId) {
+  if (!url || typeof url !== 'string') {
+    logToFile(`[Config] WARNING: instance "${instanceId}" has no URL configured`);
+    return false;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    logToFile(`[Config] WARNING: instance "${instanceId}" has an invalid URL: "${url}"`);
+    return false;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    logToFile(`[Config] WARNING: instance "${instanceId}" URL must use http or https, got "${parsed.protocol}"`);
+    return false;
+  }
+  return true;
+}
+
 function parseInstances(envVar, legacyUrl, legacyKey, legacyUsername, legacyPassword) {
   // Try to parse JSON array format first
   if (envVar) {
@@ -9,10 +32,11 @@ function parseInstances(envVar, legacyUrl, legacyKey, legacyUsername, legacyPass
       const instances = JSON.parse(cleaned);
       if (Array.isArray(instances) && instances.length > 0) {
         logToFile(`[Config] Parsed ${instances.length} instances from JSON array`);
-        return instances.map((inst, idx) => ({
-          ...inst,
-          id: inst.name || `instance-${idx + 1}`
-        }));
+        return instances.map((inst, idx) => {
+          const id = inst.name || `instance-${idx + 1}`;
+          validateInstanceUrl(inst.url, id);
+          return { ...inst, id };
+        });
       }
     } catch (err) {
       logToFile(`[Config] Failed to parse JSON array: ${err.message}`);
@@ -22,6 +46,7 @@ function parseInstances(envVar, legacyUrl, legacyKey, legacyUsername, legacyPass
   // Fall back to legacy single-instance format
   if (legacyUrl && legacyKey) {
     logToFile(`[Config] Using legacy single-instance format`);
+    validateInstanceUrl(legacyUrl, 'default');
     return [{
       id: 'default',
       name: 'Default',
@@ -69,10 +94,33 @@ function getQbittorrentInstances() {
   );
 }
 
+function getTransmissionInstances() {
+  return parseInstances(
+    process.env.TRANSMISSION_INSTANCES,
+    process.env.TRANSMISSION_URL,
+    null, // no apiKey for Transmission
+    process.env.TRANSMISSION_USERNAME,
+    process.env.TRANSMISSION_PASSWORD
+  );
+}
+
+function getRtorrentInstances() {
+  return parseInstances(
+    process.env.RTORRENT_INSTANCES,
+    process.env.RTORRENT_URL,
+    null, // no apiKey for rtorrent
+    process.env.RTORRENT_USERNAME,
+    process.env.RTORRENT_PASSWORD
+  );
+}
+
 module.exports = {
   getSABnzbdInstances,
   getSonarrInstances,
   getRadarrInstances,
   getQbittorrentInstances,
-  parseInstances
+  getTransmissionInstances,
+  getRtorrentInstances,
+  parseInstances,
+  validateInstanceUrl
 };

server/utils/downloadClients.js

@@ -0,0 +1,254 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const { logToFile } = require('./logger');
+const {
+  getSABnzbdInstances,
+  getQbittorrentInstances,
+  getTransmissionInstances,
+  getRtorrentInstances
+} = require('./config');
+
+// Import client classes
+const SABnzbdClient = require('../clients/SABnzbdClient');
+const QBittorrentClient = require('../clients/QBittorrentClient');
+const TransmissionClient = require('../clients/TransmissionClient');
+const RTorrentClient = require('../clients/RTorrentClient');
+
+// Client type mapping
+const clientClasses = {
+  sabnzbd: SABnzbdClient,
+  qbittorrent: QBittorrentClient,
+  transmission: TransmissionClient,
+  rtorrent: RTorrentClient
+};
+
+/**
+ * Registry and factory for download clients
+ */
+class DownloadClientRegistry {
+  constructor() {
+    this.clients = new Map();
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize all configured download clients
+   */
+  async initialize() {
+    if (this.initialized) {
+      return;
+    }
+
+    logToFile('[DownloadClientRegistry] Initializing download clients...');
+
+    // Get all instance configurations
+    const sabnzbdInstances = getSABnzbdInstances();
+    const qbittorrentInstances = getQbittorrentInstances();
+    const transmissionInstances = getTransmissionInstances();
+    const rtorrentInstances = getRtorrentInstances();
+
+    // Create client instances
+    const instanceConfigs = [
+      ...sabnzbdInstances.map(inst => ({ ...inst, type: 'sabnzbd' })),
+      ...qbittorrentInstances.map(inst => ({ ...inst, type: 'qbittorrent' })),
+      ...transmissionInstances.map(inst => ({ ...inst, type: 'transmission' })),
+      ...rtorrentInstances.map(inst => ({ ...inst, type: 'rtorrent' }))
+    ];
+
+    for (const config of instanceConfigs) {
+      try {
+        const ClientClass = clientClasses[config.type];
+        if (!ClientClass) {
+          logToFile(`[DownloadClientRegistry] Unknown client type: ${config.type}`);
+          continue;
+        }
+
+        const client = new ClientClass(config);
+        this.clients.set(config.id, client);
+        logToFile(`[DownloadClientRegistry] Created ${config.type} client: ${config.name} (${config.id})`);
+      } catch (error) {
+        logToFile(`[DownloadClientRegistry] Failed to create client ${config.id}: ${error.message}`);
+      }
+    }
+
+    this.initialized = true;
+    logToFile(`[DownloadClientRegistry] Initialized ${this.clients.size} download clients`);
+  }
+
+  /**
+   * Get all registered clients
+   * @returns {Array<DownloadClient>} Array of client instances
+   */
+  getAllClients() {
+    return Array.from(this.clients.values());
+  }
+
+  /**
+   * Get client by instance ID
+   * @param {string} instanceId - The instance ID
+   * @returns {DownloadClient|null} Client instance or null if not found
+   */
+  getClient(instanceId) {
+    return this.clients.get(instanceId) || null;
+  }
+
+  /**
+   * Get clients by type
+   * @param {string} type - Client type ('sabnzbd', 'qbittorrent', 'transmission')
+   * @returns {Array<DownloadClient>} Array of client instances
+   */
+  getClientsByType(type) {
+    return this.getAllClients().filter(client => client.getClientType() === type);
+  }
+
+  /**
+   * Get active downloads from all clients
+   * @returns {Promise<Array<NormalizedDownload>>} Array of all downloads
+   */
+  async getAllDownloads() {
+    const clients = this.getAllClients();
+    if (clients.length === 0) {
+      return [];
+    }
+
+    // Reset fallback flags for qBittorrent clients
+    for (const client of clients) {
+      if (client.resetFallbackFlag) {
+        client.resetFallbackFlag();
+      }
+    }
+
+    // Fetch downloads from all clients in parallel
+    const results = await Promise.allSettled(
+      clients.map(async (client) => {
+        try {
+          const downloads = await client.getActiveDownloads();
+          logToFile(`[DownloadClientRegistry] ${client.name}: ${downloads.length} downloads`);
+          return downloads;
+        } catch (error) {
+          logToFile(`[DownloadClientRegistry] Error fetching from ${client.name}: ${error.message}`);
+          return [];
+        }
+      })
+    );
+
+    // Flatten and return all downloads
+    const allDownloads = results
+      .filter(result => result.status === 'fulfilled')
+      .flatMap(result => result.value);
+
+    logToFile(`[DownloadClientRegistry] Total downloads from all clients: ${allDownloads.length}`);
+    return allDownloads;
+  }
+
+  /**
+   * Get downloads grouped by client type (for backward compatibility)
+   * @returns {Promise<Object>} Downloads grouped by client type
+   */
+  async getDownloadsByClientType() {
+    const clients = this.getAllClients();
+    const result = {};
+
+    // Group by client type
+    for (const client of clients) {
+      const type = client.getClientType();
+      if (!result[type]) {
+        result[type] = [];
+      }
+
+      try {
+        const downloads = await client.getActiveDownloads();
+        result[type].push(...downloads);
+      } catch (error) {
+        logToFile(`[DownloadClientRegistry] Error fetching from ${client.name}: ${error.message}`);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Test connection to all clients
+   * @returns {Promise<Array<Object>>} Array of connection test results
+   */
+  async testAllConnections() {
+    const clients = this.getAllClients();
+    const results = await Promise.allSettled(
+      clients.map(async (client) => {
+        try {
+          const success = await client.testConnection();
+          return {
+            instanceId: client.getInstanceId(),
+            instanceName: client.name,
+            clientType: client.getClientType(),
+            success,
+            error: null
+          };
+        } catch (error) {
+          return {
+            instanceId: client.getInstanceId(),
+            instanceName: client.name,
+            clientType: client.getClientType(),
+            success: false,
+            error: error.message
+          };
+        }
+      })
+    );
+
+    return results
+      .filter(result => result.status === 'fulfilled')
+      .map(result => result.value);
+  }
+
+  /**
+   * Get client status information from all clients
+   * @returns {Promise<Array<Object>>} Array of client status objects
+   */
+  async getAllClientStatuses() {
+    const clients = this.getAllClients();
+    const results = await Promise.allSettled(
+      clients.map(async (client) => {
+        try {
+          const status = await client.getClientStatus();
+          return {
+            instanceId: client.getInstanceId(),
+            instanceName: client.name,
+            clientType: client.getClientType(),
+            status
+          };
+        } catch (error) {
+          logToFile(`[DownloadClientRegistry] Error getting status from ${client.name}: ${error.message}`);
+          return {
+            instanceId: client.getInstanceId(),
+            instanceName: client.name,
+            clientType: client.getClientType(),
+            status: null,
+            error: error.message
+          };
+        }
+      })
+    );
+
+    return results
+      .filter(result => result.status === 'fulfilled')
+      .map(result => result.value);
+  }
+}
+
+// Create singleton instance
+const registry = new DownloadClientRegistry();
+
+module.exports = {
+  DownloadClientRegistry,
+  registry,
+  
+  // Convenience functions
+  initializeClients: () => registry.initialize(),
+  getAllClients: () => registry.getAllClients(),
+  getClient: (instanceId) => registry.getClient(instanceId),
+  getClientsByType: (type) => registry.getClientsByType(type),
+  getAllDownloads: () => registry.getAllDownloads(),
+  getDownloadsByClientType: () => registry.getDownloadsByClientType(),
+  testAllConnections: () => registry.testAllConnections(),
+  getAllClientStatuses: () => registry.getAllClientStatuses()
+};

server/utils/historyFetcher.js

@@ -0,0 +1,143 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const axios = require('axios');
+const cache = require('./cache');
+const { getSonarrInstances, getRadarrInstances } = require('./config');
+
+// Cache TTL for recent-history data: 5 minutes.
+// History changes slowly compared to active downloads.
+const HISTORY_CACHE_TTL = 5 * 60 * 1000;
+
+// Sonarr event types that represent a successful import
+const SONARR_IMPORTED_EVENTS = new Set(['downloadFolderImported', 'downloadImported']);
+// Sonarr event types that represent a failed import
+const SONARR_FAILED_EVENTS = new Set(['downloadFailed', 'importFailed']);
+// Radarr equivalents
+const RADARR_IMPORTED_EVENTS = new Set(['downloadFolderImported', 'downloadImported']);
+const RADARR_FAILED_EVENTS = new Set(['downloadFailed', 'importFailed']);
+
+/**
+ * Fetch recent history records from all Sonarr instances for the given date window.
+ * Results are cached under 'history:sonarr' for HISTORY_CACHE_TTL.
+ * @param {Date} since - Only include records on or after this date
+ * @returns {Promise<Array>} Flat array of Sonarr history records (with _instanceUrl and _instanceName)
+ */
+async function fetchSonarrHistory(since) {
+  const cacheKey = 'history:sonarr';
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+
+  const instances = getSonarrInstances();
+  const results = await Promise.all(instances.map(async inst => {
+    try {
+      const response = await axios.get(`${inst.url}/api/v3/history`, {
+        headers: { 'X-Api-Key': inst.apiKey },
+        params: {
+          pageSize: 100,
+          sortKey: 'date',
+          sortDir: 'descending',
+          includeSeries: true,
+          includeEpisode: true,
+          startDate: since.toISOString()
+        }
+      });
+      const records = (response.data && response.data.records) || [];
+      return records.map(r => {
+        if (r.series) r.series._instanceUrl = inst.url;
+        if (r.series) r.series._instanceName = inst.name || inst.id;
+        r._instanceUrl = inst.url;
+        r._instanceName = inst.name || inst.id;
+        return r;
+      });
+    } catch (err) {
+      console.error(`[HistoryFetcher] Sonarr ${inst.id} error:`, err.message);
+      return [];
+    }
+  }));
+
+  const flat = results.flat();
+  cache.set(cacheKey, flat, HISTORY_CACHE_TTL);
+  return flat;
+}
+
+/**
+ * Fetch recent history records from all Radarr instances for the given date window.
+ * Results are cached under 'history:radarr' for HISTORY_CACHE_TTL.
+ * @param {Date} since - Only include records on or after this date
+ * @returns {Promise<Array>} Flat array of Radarr history records (with _instanceUrl and _instanceName)
+ */
+async function fetchRadarrHistory(since) {
+  const cacheKey = 'history:radarr';
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+
+  const instances = getRadarrInstances();
+  const results = await Promise.all(instances.map(async inst => {
+    try {
+      const response = await axios.get(`${inst.url}/api/v3/history`, {
+        headers: { 'X-Api-Key': inst.apiKey },
+        params: {
+          pageSize: 100,
+          sortKey: 'date',
+          sortDir: 'descending',
+          includeMovie: true,
+          startDate: since.toISOString()
+        }
+      });
+      const records = (response.data && response.data.records) || [];
+      return records.map(r => {
+        if (r.movie) r.movie._instanceUrl = inst.url;
+        if (r.movie) r.movie._instanceName = inst.name || inst.id;
+        r._instanceUrl = inst.url;
+        r._instanceName = inst.name || inst.id;
+        return r;
+      });
+    } catch (err) {
+      console.error(`[HistoryFetcher] Radarr ${inst.id} error:`, err.message);
+      return [];
+    }
+  }));
+
+  const flat = results.flat();
+  cache.set(cacheKey, flat, HISTORY_CACHE_TTL);
+  return flat;
+}
+
+/**
+ * Classify a Sonarr history record's event type.
+ * @param {string} eventType
+ * @returns {'imported'|'failed'|'other'}
+ */
+function classifySonarrEvent(eventType) {
+  if (SONARR_IMPORTED_EVENTS.has(eventType)) return 'imported';
+  if (SONARR_FAILED_EVENTS.has(eventType)) return 'failed';
+  return 'other';
+}
+
+/**
+ * Classify a Radarr history record's event type.
+ * @param {string} eventType
+ * @returns {'imported'|'failed'|'other'}
+ */
+function classifyRadarrEvent(eventType) {
+  if (RADARR_IMPORTED_EVENTS.has(eventType)) return 'imported';
+  if (RADARR_FAILED_EVENTS.has(eventType)) return 'failed';
+  return 'other';
+}
+
+/**
+ * Invalidate cached history so the next request fetches fresh data.
+ * Called externally if needed (e.g. after a forced refresh).
+ */
+function invalidateHistoryCache() {
+  cache.invalidate('history:sonarr');
+  cache.invalidate('history:radarr');
+}
+
+module.exports = {
+  fetchSonarrHistory,
+  fetchRadarrHistory,
+  classifySonarrEvent,
+  classifyRadarrEvent,
+  invalidateHistoryCache,
+  HISTORY_CACHE_TTL
+};

server/utils/loadSecrets.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+//
+// Docker secrets support: if an environment variable named FOO_FILE is set,
+// read its contents from the file at that path and expose it as FOO.
+// This follows the standard *_FILE convention used by official Docker images.
+//
+// Supported secrets:
+//   COOKIE_SECRET_FILE       → COOKIE_SECRET
+//   EMBY_API_KEY_FILE        → EMBY_API_KEY
+//   SABNZBD_API_KEY_FILE     → SABNZBD_API_KEY   (legacy single-instance)
+//   SONARR_API_KEY_FILE      → SONARR_API_KEY    (legacy single-instance)
+//   RADARR_API_KEY_FILE      → RADARR_API_KEY    (legacy single-instance)
+//   QBITTORRENT_PASSWORD_FILE → QBITTORRENT_PASSWORD (legacy single-instance)
+//
+// For multi-instance JSON arrays the secret values must be embedded in the
+// JSON string itself; file-based loading is for the legacy single-key format.
+
+const fs = require('fs');
+
+const SECRET_MAPPINGS = [
+  'COOKIE_SECRET',
+  'EMBY_API_KEY',
+  'SABNZBD_API_KEY',
+  'SONARR_API_KEY',
+  'RADARR_API_KEY',
+  'QBITTORRENT_PASSWORD',
+];
+
+function loadSecrets() {
+  for (const key of SECRET_MAPPINGS) {
+    const fileEnv = `${key}_FILE`;
+    const filePath = process.env[fileEnv];
+    if (!filePath) continue;
+    if (process.env[key]) {
+      console.warn(`[Secrets] Both ${key} and ${fileEnv} are set — ${fileEnv} takes precedence`);
+    }
+    try {
+      const value = fs.readFileSync(filePath, 'utf8').trim();
+      if (!value) {
+        console.warn(`[Secrets] ${fileEnv} points to an empty file: ${filePath}`);
+        continue;
+      }
+      process.env[key] = value;
+      console.log(`[Secrets] Loaded ${key} from ${fileEnv}`);
+    } catch (err) {
+      console.error(`[Secrets] Failed to read ${fileEnv} (${filePath}): ${err.message}`);
+      process.exit(1);
+    }
+  }
+}
+
+module.exports = loadSecrets;

server/utils/logger.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const fs = require('fs');
 const path = require('path');
 

server/utils/poller.js

@@ -1,8 +1,8 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 const axios = require('axios');
 const cache = require('./cache');
-const { getTorrents } = require('./qbittorrent');
+const { initializeClients, getAllDownloads, getDownloadsByClientType } = require('./downloadClients');
 const {
-  getSABnzbdInstances,
   getSonarrInstances,
   getRadarrInstances
 } = require('./config');
@@ -38,28 +38,18 @@ async function pollAllServices() {
   const start = Date.now();
 
   try {
-    const sabInstances = getSABnzbdInstances();
+    // Ensure download clients are initialized
+    await initializeClients();
+
     const sonarrInstances = getSonarrInstances();
     const radarrInstances = getRadarrInstances();
 
     // All fetches in parallel, each individually timed
     const results = await Promise.all([
-      timed('SABnzbd Queue', () => Promise.all(sabInstances.map(inst =>
-        axios.get(`${inst.url}/api`, {
-          params: { mode: 'queue', apikey: inst.apiKey, output: 'json' }
-        }).then(res => ({ instance: inst.id, data: res.data })).catch(err => {
-          console.error(`[Poller] SABnzbd ${inst.id} queue error:`, err.message);
-          return { instance: inst.id, data: { queue: { slots: [] } } };
-        })
-      ))),
-      timed('SABnzbd History', () => Promise.all(sabInstances.map(inst =>
-        axios.get(`${inst.url}/api`, {
-          params: { mode: 'history', apikey: inst.apiKey, output: 'json', limit: 10 }
-        }).then(res => ({ instance: inst.id, data: res.data })).catch(err => {
-          console.error(`[Poller] SABnzbd ${inst.id} history error:`, err.message);
-          return { instance: inst.id, data: { history: { slots: [] } } };
-        })
-      ))),
+      timed('Download Clients', async () => {
+        const downloadsByType = await getDownloadsByClientType();
+        return downloadsByType;
+      }),
       timed('Sonarr Tags', () => Promise.all(sonarrInstances.map(inst =>
         axios.get(`${inst.url}/api/v3/tag`, {
           headers: { 'X-Api-Key': inst.apiKey }
@@ -71,7 +61,7 @@ async function pollAllServices() {
       timed('Sonarr Queue', () => Promise.all(sonarrInstances.map(inst =>
         axios.get(`${inst.url}/api/v3/queue`, {
           headers: { 'X-Api-Key': inst.apiKey },
-          params: { includeSeries: true }
+          params: { includeSeries: true, includeEpisode: true }
         }).then(res => ({ instance: inst.id, data: res.data })).catch(err => {
           console.error(`[Poller] Sonarr ${inst.id} queue error:`, err.message);
           return { instance: inst.id, data: { records: [] } };
@@ -80,7 +70,7 @@ async function pollAllServices() {
       timed('Sonarr History', () => Promise.all(sonarrInstances.map(inst =>
         axios.get(`${inst.url}/api/v3/history`, {
           headers: { 'X-Api-Key': inst.apiKey },
-          params: { pageSize: 10 }
+          params: { pageSize: 10, includeEpisode: true }
         }).then(res => ({ instance: inst.id, data: res.data })).catch(err => {
           console.error(`[Poller] Sonarr ${inst.id} history error:`, err.message);
           return { instance: inst.id, data: { records: [] } };
@@ -112,19 +102,14 @@ async function pollAllServices() {
           return { instance: inst.id, data: [] };
         })
       ))),
-      timed('qBittorrent', () => getTorrents().catch(err => {
-        console.error(`[Poller] qBittorrent error:`, err.message);
-        return [];
-      }))
     ]);
 
     const [
-      { result: sabQueues }, { result: sabHistories },
+      { result: downloadsByType },
       { result: sonarrTagsResults }, { result: sonarrQueues },
       { result: sonarrHistories },
       { result: radarrQueues }, { result: radarrHistories },
-      { result: radarrTagsResults },
-      { result: qbittorrentTorrents }
+      { result: radarrTagsResults }
     ] = results;
 
     // Store per-task timings
@@ -139,18 +124,69 @@ async function pollAllServices() {
     // When polling is disabled (on-demand), use 30s so data refreshes on next request after expiry
     const cacheTTL = POLLING_ENABLED ? POLL_INTERVAL * 3 : 30000;
 
-    // SABnzbd
-    const firstSabQueue = sabQueues[0] && sabQueues[0].data && sabQueues[0].data.queue;
+    // Download Clients (SABnzbd, qBittorrent, Transmission)
+    // Preserve backward compatibility with existing cache keys
+    const sabnzbdDownloads = downloadsByType.sabnzbd || [];
+    const qbittorrentDownloads = downloadsByType.qbittorrent || [];
+    
+    // SABnzbd - separate queue and history based on source
+    const sabQueue = sabnzbdDownloads.filter(d => d.raw && d.raw.source === 'queue');
+    const sabHistory = sabnzbdDownloads.filter(d => d.raw && d.raw.source === 'history');
+    
+    // Transform SABnzbd downloads to legacy format for cache
+    const sabQueueLegacy = {
+      slots: sabQueue.map(d => ({
+        nzo_id: d.id,
+        filename: d.title,
+        status: d.status,
+        progress: d.progress / 100,
+        mb: d.size / (1024 * 1024),
+        mbleft: (d.size - d.downloaded) / (1024 * 1024),
+        kbpersec: d.speed / 1024,
+        timeleft: d.eta ? `${Math.floor(d.eta / 60)}:${String(Math.floor(d.eta % 60)).padStart(2, '0')}` : 'unknown',
+        cat: d.category,
+        labels: d.tags.join(','),
+        added: d.addedOn ? Math.floor(new Date(d.addedOn).getTime() / 1000) : null,
+        raw: d.raw
+      }))
+    };
+    
+    const sabHistoryLegacy = {
+      slots: sabHistory.map(d => ({
+        nzo_id: d.id,
+        filename: d.title,
+        status: d.status,
+        mb: d.size / (1024 * 1024),
+        cat: d.category,
+        labels: d.tags.join(','),
+        added: d.addedOn ? Math.floor(new Date(d.addedOn).getTime() / 1000) : null,
+        raw: d.raw
+      }))
+    };
+    
+    // Extract status from first SABnzbd download if available
+    const firstSabDownload = sabQueue[0];
+    const sabStatus = firstSabDownload ? {
+      status: 'Active',
+      speed: firstSabDownload.speed,
+      kbpersec: firstSabDownload.speed / 1024
+    } : { status: 'Idle', speed: 0, kbpersec: 0 };
+    
     cache.set('poll:sab-queue', {
-      slots: sabQueues.flatMap(q => (q.data.queue && q.data.queue.slots) || []),
-      status: firstSabQueue && firstSabQueue.status,
-      speed: firstSabQueue && firstSabQueue.speed,
-      kbpersec: firstSabQueue && firstSabQueue.kbpersec
-    }, cacheTTL);
-
-    cache.set('poll:sab-history', {
-      slots: sabHistories.flatMap(h => (h.data.history && h.data.history.slots) || [])
+      ...sabQueueLegacy,
+      ...sabStatus
     }, cacheTTL);
+    
+    cache.set('poll:sab-history', sabHistoryLegacy, cacheTTL);
+    
+    // qBittorrent - transform to legacy format
+    const qbittorrentLegacy = qbittorrentDownloads.map(d => ({
+      ...d.raw,
+      instanceId: d.instanceId,
+      instanceName: d.instanceName
+    }));
+    
+    cache.set('poll:qbittorrent', qbittorrentLegacy, cacheTTL);
 
     // Sonarr
     cache.set('poll:sonarr-tags', sonarrTagsResults, cacheTTL);
@@ -159,8 +195,11 @@ async function pollAllServices() {
       records: sonarrQueues.flatMap(q => {
         const inst = sonarrInstances.find(i => i.id === q.instance);
         const url = inst ? inst.url : null;
+        const key = inst ? inst.apiKey : null;
         return (q.data.records || []).map(r => {
           if (r.series) r.series._instanceUrl = url;
+          r._instanceUrl = url;
+          r._instanceKey = key;
           return r;
         });
       })
@@ -174,8 +213,11 @@ async function pollAllServices() {
       records: radarrQueues.flatMap(q => {
         const inst = radarrInstances.find(i => i.id === q.instance);
         const url = inst ? inst.url : null;
+        const key = inst ? inst.apiKey : null;
         return (q.data.records || []).map(r => {
           if (r.movie) r.movie._instanceUrl = url;
+          r._instanceUrl = url;
+          r._instanceKey = key;
           return r;
         });
       })
@@ -185,8 +227,7 @@ async function pollAllServices() {
     }, cacheTTL);
     cache.set('poll:radarr-tags', radarrTagsResults.flatMap(t => t.data || []), cacheTTL);
 
-    // qBittorrent
-    cache.set('poll:qbittorrent', qbittorrentTorrents, cacheTTL);
+    // qBittorrent (already set above in download clients section)
 
     const elapsed = Date.now() - start;
     console.log(`[Poller] Poll complete in ${elapsed}ms`);

server/utils/qbittorrent.js

@@ -1,132 +1,47 @@
-const axios = require('axios');
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+// Legacy compatibility layer - delegates to new DownloadClient system
 const { logToFile } = require('./logger');
-const { getQbittorrentInstances } = require('./config');
-
-class QBittorrentClient {
-  constructor(instance) {
-    this.id = instance.id;
-    this.name = instance.name;
-    this.url = instance.url;
-    this.username = instance.username;
-    this.password = instance.password;
-    this.authCookie = null;
-  }
-
-  async login() {
-    try {
-      logToFile(`[qBittorrent:${this.name}] Attempting login...`);
-      const response = await axios.post(`${this.url}/api/v2/auth/login`, 
-        `username=${encodeURIComponent(this.username)}&password=${encodeURIComponent(this.password)}`,
-        {
-          headers: {
-            'Content-Type': 'application/x-www-form-urlencoded'
-          },
-          maxRedirects: 0,
-          validateStatus: (status) => status >= 200 && status < 400
-        }
-      );
-      
-      if (response.headers['set-cookie']) {
-        this.authCookie = response.headers['set-cookie'][0];
-        logToFile(`[qBittorrent:${this.name}] Login successful`);
-        return true;
-      }
-      
-      logToFile(`[qBittorrent:${this.name}] Login failed - no cookie`);
-      return false;
-    } catch (error) {
-      logToFile(`[qBittorrent:${this.name}] Login error: ${error.message}`);
-      return false;
-    }
-  }
-
-  async makeRequest(endpoint, config = {}) {
-    const url = `${this.url}${endpoint}`;
-    
-    if (!this.authCookie) {
-      const loggedIn = await this.login();
-      if (!loggedIn) {
-        throw new Error(`Failed to authenticate with ${this.name}`);
-      }
-    }
-    
-    try {
-      const response = await axios.get(url, {
-        ...config,
-        headers: {
-          ...config.headers,
-          'Cookie': this.authCookie
-        }
-      });
-      return response;
-    } catch (error) {
-      // If unauthorized, try re-authenticating once
-      if (error.response && error.response.status === 403) {
-        logToFile(`[qBittorrent:${this.name}] Auth expired, re-authenticating...`);
-        this.authCookie = null;
-        const loggedIn = await this.login();
-        if (loggedIn) {
-          return axios.get(url, {
-            ...config,
-            headers: {
-              ...config.headers,
-              'Cookie': this.authCookie
-            }
-          });
-        }
-      }
-      throw error;
-    }
-  }
-
-  async getTorrents() {
-    try {
-      const response = await this.makeRequest('/api/v2/torrents/info');
-      logToFile(`[qBittorrent:${this.name}] Retrieved ${response.data.length} torrents`);
-      // Add instance info to each torrent
-      return response.data.map(torrent => ({
-        ...torrent,
-        instanceId: this.id,
-        instanceName: this.name
-      }));
-    } catch (error) {
-      logToFile(`[qBittorrent:${this.name}] Error fetching torrents: ${error.message}`);
-      return [];
-    }
-  }
-}
-
-// Persist clients so auth cookies survive between requests
-let persistedClients = null;
-
-function getClients() {
-  if (persistedClients) return persistedClients;
-  const instances = getQbittorrentInstances();
-  if (instances.length === 0) {
-    logToFile('[qBittorrent] No instances configured');
-    return [];
-  }
-  logToFile(`[qBittorrent] Created ${instances.length} persistent client(s)`);
-  persistedClients = instances.map(inst => new QBittorrentClient(inst));
-  return persistedClients;
-}
+const { initializeClients, getClientsByType } = require('./downloadClients');
 
+/**
+ * Legacy function for backward compatibility
+ * Returns all torrents from all qBittorrent instances
+ */
 async function getAllTorrents() {
-  const clients = getClients();
-  if (clients.length === 0) {
+  try {
+    await initializeClients();
+    const clients = getClientsByType('qbittorrent');
+    
+    if (clients.length === 0) {
+      logToFile('[qBittorrent] No instances configured');
+      return [];
+    }
+
+    const results = await Promise.all(
+      clients.map(client => client.getActiveDownloads().catch(err => {
+        logToFile(`[qBittorrent] Error from ${client.name}: ${err.message}`);
+        return [];
+      }))
+    );
+    
+    const allTorrents = results.flat();
+    // Convert back to legacy format for backward compatibility
+    const legacyTorrents = allTorrents.map(download => download.raw);
+    
+    logToFile(`[qBittorrent] Total torrents from all instances: ${legacyTorrents.length}`);
+    return legacyTorrents;
+  } catch (error) {
+    logToFile(`[qBittorrent] Error in getAllTorrents: ${error.message}`);
     return [];
   }
-  
-  const results = await Promise.all(
-    clients.map(client => client.getTorrents().catch(err => {
-      logToFile(`[qBittorrent] Error from ${client.name}: ${err.message}`);
-      return [];
-    }))
-  );
-  
-  const allTorrents = results.flat();
-  logToFile(`[qBittorrent] Total torrents from all instances: ${allTorrents.length}`);
-  return allTorrents;
+}
+
+/**
+ * Legacy function for backward compatibility
+ */
+function getClients() {
+  logToFile('[qBittorrent] getClients() called - delegating to new system');
+  return []; // Not used in new system
 }
 
 function formatBytes(bytes) {
@@ -204,12 +119,13 @@ function mapTorrentToDownload(torrent) {
     category: torrent.category,
     tags: torrent.tags,
     savePath: torrent.content_path || torrent.save_path || null,
+    addedOn: torrent.added_on || null,
     qbittorrent: true
   };
 }
 
 module.exports = {
-  getTorrents: getAllTorrents,
+  getAllTorrents,
   getClients,
   mapTorrentToDownload,
   formatBytes,

server/utils/sanitizeError.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 // Query-param secrets (SABnzbd apikey, generic token/password params)
 const QUERY_SECRET_PATTERN = /([?&](?:apikey|token|password|api_key|key|secret)=)[^&\s#]*/gi;
 // HTTP auth header values (X-Api-Key, X-MediaBrowser-Token, Authorization, X-Emby-Authorization)
@@ -7,13 +8,18 @@ const HEADER_PATTERN = /(?:x-api-key|x-mediabrowser-token|x-emby-authorization|a
 const BEARER_PATTERN = /bearer\s+[A-Za-z0-9\-._~+/]+=*/gi;
 // Basic auth credentials in URLs (http://user:pass@host)
 const BASIC_AUTH_URL_PATTERN = /\/\/[^:@/\s]+:[^@/\s]+@/gi;
+// Redact only the host:port authority portion of URLs, preserving path/query so
+// other patterns (QUERY_SECRET_PATTERN etc.) can still act on them.
+// Negative lookahead skips URLs already handled by BASIC_AUTH_URL_PATTERN.
+const HOST_PATTERN = /(https?:\/\/)(?!\[REDACTED\]@)([^\s/?#]+)/gi;
 
 function sanitizeError(err) {
   let msg = (err && err.message) ? err.message : String(err);
   msg = msg.replace(QUERY_SECRET_PATTERN, '$1[REDACTED]');
   msg = msg.replace(HEADER_PATTERN, (m) => m.split(/[\s:]/)[0] + ':[REDACTED]');
   msg = msg.replace(BEARER_PATTERN, 'bearer [REDACTED]');
-  msg = msg.replace(BASIC_AUTH_URL_PATTERN, '//[REDACTED]@');
+  msg = msg.replace(BASIC_AUTH_URL_PATTERN, '//[REDACTED]@');  // must run before HOST_PATTERN
+  msg = msg.replace(HOST_PATTERN, '$1[HOST]');
   // Never leak stack traces to API responses
   return msg;
 }

server/utils/tokenStore.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Persistent token store backed by a JSON file.
  *

tests/integration/auth.test.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Integration tests for authentication routes.
  *

tests/integration/downloadClients.test.js

@@ -0,0 +1,300 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+import {
+  initializeClients,
+  getAllDownloads,
+  getDownloadsByClientType,
+  testAllConnections,
+  registry
+} from '../../server/utils/downloadClients.js';
+import axios from 'axios';
+import { vi } from 'vitest';
+
+// Mock environment variables for testing
+process.env.SABNZBD_INSTANCES = JSON.stringify([
+  {
+    id: 'test-sab',
+    name: 'Test SABnzbd',
+    url: 'http://localhost:8080',
+    apiKey: 'test-api-key'
+  }
+]);
+
+process.env.QBITTORRENT_INSTANCES = JSON.stringify([
+  {
+    id: 'test-qb',
+    name: 'Test qBittorrent',
+    url: 'http://localhost:8080',
+    username: 'admin',
+    password: 'adminadmin'
+  }
+]);
+
+process.env.TRANSMISSION_INSTANCES = JSON.stringify([
+  {
+    id: 'test-trans',
+    name: 'Test Transmission',
+    url: 'http://localhost:9091',
+    username: 'transmission',
+    password: 'transmission'
+  }
+]);
+
+process.env.RTORRENT_INSTANCES = JSON.stringify([
+  {
+    id: 'test-rtorrent',
+    name: 'Test rTorrent',
+    url: 'http://localhost:8080/RPC2',
+    username: 'rtorrent',
+    password: 'rtorrent'
+  }
+]);
+
+// Mock axios to prevent actual network calls
+vi.mock('axios', () => {
+  const mockAxios = vi.fn();
+  mockAxios.post = vi.fn();
+  mockAxios.get = vi.fn();
+  return {
+    default: mockAxios,
+    post: vi.fn(),
+    get: vi.fn()
+  };
+});
+vi.mock('../../server/utils/logger', () => ({
+  logToFile: vi.fn()
+}));
+
+describe('Download Clients Integration Tests', () => {
+  beforeEach(() => {
+    registry.initialized = false;
+    registry.clients.clear();
+    vi.clearAllMocks();
+  });
+
+  describe('Client Initialization', () => {
+    it('should initialize all configured client types', async () => {
+      await initializeClients();
+      
+      // The registry should have clients for all three types
+      const downloadsByType = await getDownloadsByClientType();
+      
+      // Should have keys for each client type (even if empty due to mocked failures)
+      expect(typeof downloadsByType).toBe('object');
+    });
+
+    it('should handle missing environment variables gracefully', async () => {
+      // Temporarily clear environment variables
+      const originalSab = process.env.SABNZBD_INSTANCES;
+      const originalQb = process.env.QBITTORRENT_INSTANCES;
+      const originalTrans = process.env.TRANSMISSION_INSTANCES;
+      const originalRt = process.env.RTORRENT_INSTANCES;
+      
+      delete process.env.SABNZBD_INSTANCES;
+      delete process.env.QBITTORRENT_INSTANCES;
+      delete process.env.TRANSMISSION_INSTANCES;
+      delete process.env.RTORRENT_INSTANCES;
+      
+      await initializeClients();
+      
+      const downloadsByType = await getDownloadsByClientType();
+      expect(Object.keys(downloadsByType)).toHaveLength(0);
+      
+      // Restore environment variables
+      process.env.SABNZBD_INSTANCES = originalSab;
+      process.env.QBITTORRENT_INSTANCES = originalQb;
+      process.env.TRANSMISSION_INSTANCES = originalTrans;
+      process.env.RTORRENT_INSTANCES = originalRt;
+    });
+  });
+
+  describe('Download Aggregation', () => {
+    it('should aggregate downloads from multiple client types', async () => {
+      await initializeClients();
+      
+      const downloadsByType = await getDownloadsByClientType();
+      const allDownloads = await getAllDownloads();
+      
+      // Should return downloads grouped by type
+      expect(typeof downloadsByType).toBe('object');
+      
+      // Should return flattened array of all downloads
+      expect(Array.isArray(allDownloads)).toBe(true);
+      
+      // All downloads should have required normalized fields
+      allDownloads.forEach(download => {
+        expect(download).toHaveProperty('id');
+        expect(download).toHaveProperty('title');
+        expect(download).toHaveProperty('type');
+        expect(download).toHaveProperty('client');
+        expect(download).toHaveProperty('instanceId');
+        expect(download).toHaveProperty('instanceName');
+        expect(download).toHaveProperty('status');
+        expect(download).toHaveProperty('progress');
+        expect(download).toHaveProperty('size');
+        expect(download).toHaveProperty('downloaded');
+        expect(download).toHaveProperty('speed');
+        expect(download).toHaveProperty('raw');
+      });
+    });
+
+    it('should maintain type consistency across clients', async () => {
+      await initializeClients();
+      
+      const downloadsByType = await getDownloadsByClientType();
+      
+      // Check that each client type returns consistent data structure
+      Object.entries(downloadsByType).forEach(([clientType, downloads]) => {
+        if (downloads.length > 0) {
+          downloads.forEach(download => {
+            expect(download.client).toBe(clientType);
+            expect(download.type).toMatch(/^(usenet|torrent)$/);
+            expect(typeof download.progress).toBe('number');
+            expect(download.progress).toBeGreaterThanOrEqual(0);
+            expect(download.progress).toBeLessThanOrEqual(100);
+            expect(typeof download.size).toBe('number');
+            expect(typeof download.downloaded).toBe('number');
+            expect(typeof download.speed).toBe('number');
+          });
+        }
+      });
+    });
+  });
+
+  describe('Connection Testing', () => {
+    it('should test connections for all configured clients', async () => {
+      await initializeClients();
+      
+      const results = await testAllConnections();
+      
+      expect(Array.isArray(results)).toBe(true);
+      
+      results.forEach(result => {
+        expect(result).toHaveProperty('instanceId');
+        expect(result).toHaveProperty('instanceName');
+        expect(result).toHaveProperty('clientType');
+        expect(result).toHaveProperty('success');
+        expect(typeof result.success).toBe('boolean');
+      });
+    });
+
+    it('should handle connection failures gracefully', async () => {
+      // This test verifies that connection failures don't crash the system
+      await initializeClients();
+      
+      const results = await testAllConnections();
+      
+      // Should still return results even if connections fail
+      expect(results.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Error Handling and Resilience', () => {
+    it('should handle individual client failures without affecting others', async () => {
+      await initializeClients();
+      
+      // Even if some clients fail, others should still work
+      const downloadsByType = await getDownloadsByClientType();
+      const allDownloads = await getAllDownloads();
+      
+      expect(typeof downloadsByType).toBe('object');
+      expect(Array.isArray(allDownloads)).toBe(true);
+    });
+
+    it('should handle malformed configuration gracefully', async () => {
+      // Test with malformed JSON
+      const originalSab = process.env.SABNZBD_INSTANCES;
+      process.env.SABNZBD_INSTANCES = 'invalid-json{';
+      
+      // Should not throw an error
+      await expect(initializeClients()).resolves.not.toThrow();
+      
+      // Restore
+      process.env.SABNZBD_INSTANCES = originalSab;
+    });
+
+    it('should handle network timeouts and errors', async () => {
+      await initializeClients();
+      
+      // Mock network failures by setting up axios to reject
+      axios.get.mockRejectedValue(new Error('Network timeout'));
+      axios.post.mockRejectedValue(new Error('Network timeout'));
+      
+      // Should handle errors gracefully and return empty results
+      const downloads = await getAllDownloads();
+      expect(Array.isArray(downloads)).toBe(true);
+    });
+  });
+
+  describe('Backward Compatibility', () => {
+    it('should maintain compatibility with existing cache structure', async () => {
+      await initializeClients();
+      
+      const downloadsByType = await getDownloadsByClientType();
+      
+      // SABnzbd downloads should have raw data for legacy compatibility
+      if (downloadsByType.sabnzbd && downloadsByType.sabnzbd.length > 0) {
+        downloadsByType.sabnzbd.forEach(download => {
+          expect(download.raw).toBeTruthy();
+          expect(download.raw.source).toMatch(/^(queue|history)$/);
+        });
+      }
+      
+      // qBittorrent downloads should have raw data for legacy compatibility
+      if (downloadsByType.qbittorrent && downloadsByType.qbittorrent.length > 0) {
+        downloadsByType.qbittorrent.forEach(download => {
+          expect(download.raw).toBeTruthy();
+          expect(download.raw.hash).toBeTruthy(); // qBittorrent specific field
+        });
+      }
+    });
+  });
+
+  describe('Performance and Scalability', () => {
+    it('should handle multiple instances of the same client type', async () => {
+      // Configure multiple instances
+      process.env.QBITTORRENT_INSTANCES = JSON.stringify([
+        {
+          id: 'test-qb-1',
+          name: 'Test qBittorrent 1',
+          url: 'http://localhost:8080',
+          username: 'admin',
+          password: 'adminadmin'
+        },
+        {
+          id: 'test-qb-2',
+          name: 'Test qBittorrent 2',
+          url: 'http://localhost:8081',
+          username: 'admin',
+          password: 'adminadmin'
+        }
+      ]);
+      
+      await initializeClients();
+      
+      const downloadsByType = await getDownloadsByClientType();
+      
+      // Should aggregate downloads from both instances
+      expect(Array.isArray(downloadsByType.qbittorrent)).toBe(true);
+      
+      // Each download should have correct instance information
+      downloadsByType.qbittorrent.forEach(download => {
+        expect(download.instanceId).toMatch(/^(test-qb-1|test-qb-2)$/);
+        expect(download.instanceName).toMatch(/^(Test qBittorrent 1|Test qBittorrent 2)$/);
+      });
+    });
+
+    it('should execute client requests in parallel', async () => {
+      const startTime = Date.now();
+      
+      await initializeClients();
+      await getAllDownloads();
+      
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+      
+      // This is a rough check - in a real scenario with actual network calls,
+      // parallel execution should be significantly faster than sequential
+      expect(duration).toBeGreaterThan(0);
+    });
+  });
+});

tests/integration/health.test.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Integration tests for health and readiness endpoints.
  *

tests/integration/history.test.js

@@ -0,0 +1,401 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+/**
+ * Integration tests for GET /api/history/recent
+ *
+ * Uses supertest against createApp() with vi.mock to stub historyFetcher
+ * (avoids nock/ESM-CJS interop issues with axios) and nock for Emby auth.
+ * Covers:
+ *  - 401 when unauthenticated
+ *  - Empty history response when arr returns no records
+ *  - Filters out records whose eventType is not imported/failed
+ *  - Returns imported and failed records for tagged series/movies
+ *  - ?days= param is respected (default 7, capped at 90)
+ *  - failureMessage included for admins on failed records
+ */
+
+import request from 'supertest';
+import nock from 'nock';
+import { beforeEach, afterEach } from 'vitest';
+import { createRequire } from 'module';
+import { createApp } from '../../server/app.js';
+
+// Use createRequire to get the same CJS singleton cache instance that
+// server/utils/historyFetcher.js and server/routes/history.js use via
+// require('./cache'). A plain ESM `import cache from '...'` resolves
+// to a different module identity under vitest's ESM runtime.
+const require = createRequire(import.meta.url);
+const cache = require('../../server/utils/cache.js');
+
+const EMBY_BASE = 'https://emby.test';
+
+process.env.EMBY_URL = EMBY_BASE;
+process.env.SONARR_INSTANCES = JSON.stringify([
+  { id: 'sonarr-1', name: 'Main Sonarr', url: 'https://sonarr.test', apiKey: 'sk' }
+]);
+process.env.RADARR_INSTANCES = JSON.stringify([
+  { id: 'radarr-1', name: 'Main Radarr', url: 'https://radarr.test', apiKey: 'rk' }
+]);
+
+// --- Fixtures ---
+const EMBY_AUTH = { AccessToken: 'tok', User: { Id: 'uid1', Name: 'alice' } };
+const EMBY_USER = { Id: 'uid1', Name: 'alice', Policy: { IsAdministrator: false } };
+const EMBY_ADMIN = { Id: 'uid2', Name: 'admin', Policy: { IsAdministrator: true } };
+const EMBY_AUTH_ADMIN = { AccessToken: 'tok2', User: { Id: 'uid2', Name: 'admin' } };
+
+// Sonarr tag: id 1 → 'alice'
+const SONARR_TAGS = [{ id: 1, label: 'alice' }];
+
+const SONARR_RECORD_IMPORTED = {
+  id: 100,
+  eventType: 'downloadFolderImported',
+  sourceTitle: 'Show.S01E01.720p',
+  date: new Date().toISOString(),
+  quality: { quality: { name: '720p' } },
+  series: { id: 10, title: 'My Show', titleSlug: 'my-show', tags: [1], images: [] },
+  seriesId: 10
+};
+
+const SONARR_RECORD_FAILED = {
+  id: 101,
+  eventType: 'downloadFailed',
+  sourceTitle: 'Show.S01E02.720p',
+  date: new Date().toISOString(),
+  quality: { quality: { name: '720p' } },
+  data: { message: 'Not enough disk space' },
+  series: { id: 11, title: 'Admin Show', titleSlug: 'admin-show', tags: [2], images: [] },
+};
+
+// Tag id 2 → 'admin' (used in the failed-import admin test)
+const SONARR_TAGS_WITH_ADMIN = [{ id: 1, label: 'alice' }, { id: 2, label: 'admin' }];
+
+const SONARR_RECORD_FAILED_ALICE = { // failed record tagged alice, for event-type filtering test
+  id: 103,
+  eventType: 'downloadFailed',
+  sourceTitle: 'Show.S01E02.720p',
+  date: new Date().toISOString(),
+  quality: { quality: { name: '720p' } },
+  data: { message: 'Disk full' },
+  series: { id: 10, title: 'My Show', titleSlug: 'my-show', tags: [1], images: [] },
+  seriesId: 10
+};
+
+const SONARR_RECORD_GRABBED = {
+  id: 102,
+  eventType: 'grabbed',
+  sourceTitle: 'Show.S01E03.720p',
+  date: new Date().toISOString(),
+  series: { id: 10, title: 'My Show', titleSlug: 'my-show', tags: [1], images: [] },
+  seriesId: 10
+};
+
+const RADARR_RECORD_IMPORTED = {
+  id: 200,
+  eventType: 'downloadFolderImported',
+  sourceTitle: 'My.Movie.2024.1080p',
+  date: new Date().toISOString(),
+  quality: { quality: { name: '1080p' } },
+  movie: { id: 20, title: 'My Movie', titleSlug: 'my-movie-2024', tags: [1], images: [] },
+  movieId: 20
+};
+
+// Deduplication fixtures — same episodeId 55, episode 1 failed then imported
+const SONARR_RECORD_FAILED_EP55 = {
+  id: 110,
+  eventType: 'downloadFailed',
+  sourceTitle: 'Show.S02E01.720p',
+  date: new Date(Date.now() - 3600000).toISOString(), // 1 hour ago
+  quality: { quality: { name: '720p' } },
+  data: { message: 'Download failed' },
+  episodeId: 55,
+  episode: { seasonNumber: 2, episodeNumber: 1, title: 'Pilot', hasFile: false },
+  series: { id: 10, title: 'My Show', titleSlug: 'my-show', tags: [1], images: [] },
+  seriesId: 10
+};
+
+const SONARR_RECORD_IMPORTED_EP55 = {
+  id: 111,
+  eventType: 'downloadFolderImported',
+  sourceTitle: 'Show.S02E01.720p',
+  date: new Date().toISOString(), // now (more recent)
+  quality: { quality: { name: '720p' } },
+  episodeId: 55,
+  episode: { seasonNumber: 2, episodeNumber: 1, title: 'Pilot', hasFile: true },
+  series: { id: 10, title: 'My Show', titleSlug: 'my-show', tags: [1], images: [] },
+  seriesId: 10
+};
+
+// Failed, still failing (hasFile=false) — most recent is a failure with no file
+const SONARR_RECORD_FAILED_EP56 = {
+  id: 112,
+  eventType: 'downloadFailed',
+  sourceTitle: 'Show.S02E02.720p',
+  date: new Date().toISOString(),
+  quality: { quality: { name: '720p' } },
+  data: { message: 'No seeders' },
+  episodeId: 56,
+  episode: { seasonNumber: 2, episodeNumber: 2, title: 'Episode 2', hasFile: false },
+  series: { id: 10, title: 'My Show', titleSlug: 'my-show', tags: [1], images: [] },
+  seriesId: 10
+};
+
+// Failed but hasFile=true — episode is available, failure is an upgrade attempt
+const SONARR_RECORD_FAILED_EP57_HAS_FILE = {
+  id: 113,
+  eventType: 'downloadFailed',
+  sourceTitle: 'Show.S02E03.720p',
+  date: new Date().toISOString(),
+  quality: { quality: { name: '720p' } },
+  data: { message: 'Upgrade failed' },
+  episodeId: 57,
+  episode: { seasonNumber: 2, episodeNumber: 3, title: 'Episode 3', hasFile: true },
+  series: { id: 10, title: 'My Show', titleSlug: 'my-show', tags: [1], images: [] },
+  seriesId: 10
+};
+
+// --- Helpers ---
+function interceptLogin(userBody = EMBY_USER, authBody = EMBY_AUTH) {
+  nock(EMBY_BASE).post('/Users/authenticatebyname').reply(200, authBody);
+  nock(EMBY_BASE).get(/\/Users\//).reply(200, userBody);
+}
+
+// Pre-seed the history cache keys that fetchSonarrHistory/fetchRadarrHistory check
+// first, so they return without making any HTTP calls.
+const CACHE_TTL = 60 * 60 * 1000; // 1 hour — won't expire during a test run
+
+function setHistory(sonarrRecords = [], radarrRecords = []) {
+  cache.set('history:sonarr', sonarrRecords.map(r => ({
+    ...r,
+    _instanceName: 'Main Sonarr',
+    series: r.series ? { ...r.series, _instanceUrl: 'https://sonarr.test', _instanceName: 'Main Sonarr' } : undefined
+  })), CACHE_TTL);
+  cache.set('history:radarr', radarrRecords.map(r => ({
+    ...r,
+    _instanceName: 'Main Radarr',
+    movie: r.movie ? { ...r.movie, _instanceUrl: 'https://radarr.test', _instanceName: 'Main Radarr' } : undefined
+  })), CACHE_TTL);
+}
+
+async function loginAs(app, userBody = EMBY_USER, authBody = EMBY_AUTH) {
+  interceptLogin(userBody, authBody);
+  const res = await request(app)
+    .post('/api/auth/login')
+    .send({ username: userBody.Name, password: 'pw' });
+  const cookies = res.headers['set-cookie'];
+  const csrf = res.body.csrfToken;
+  return { cookies, csrf };
+}
+
+beforeEach(() => {
+  // Clear history caches so each test controls its own data
+  cache.invalidate('history:sonarr');
+  cache.invalidate('history:radarr');
+  // Default: empty history
+  setHistory([], []);
+  // Seed poll tag caches so the route can resolve tags
+  cache.set('poll:sonarr-tags', [{ data: SONARR_TAGS }], 60000);
+  cache.set('poll:radarr-tags', [], 60000);
+});
+
+afterEach(() => {
+  nock.cleanAll();
+  cache.invalidate('history:sonarr');
+  cache.invalidate('history:radarr');
+});
+
+describe('GET /api/history/recent', () => {
+  describe('authentication', () => {
+    it('returns 401 when not logged in', async () => {
+      const app = createApp({ skipRateLimits: true });
+      const res = await request(app).get('/api/history/recent');
+      expect(res.status).toBe(401);
+    });
+  });
+
+  describe('empty history', () => {
+    it('returns empty array when arr returns no records', async () => {
+      const app = createApp({ skipRateLimits: true });
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      expect(res.body.history).toEqual([]);
+      expect(res.body.days).toBe(7);
+    });
+  });
+
+  describe('event type filtering', () => {
+    it('includes imported and failed records, excludes grabbed', async () => {
+      const app = createApp({ skipRateLimits: true });
+      setHistory(
+        [SONARR_RECORD_IMPORTED, SONARR_RECORD_FAILED_ALICE, SONARR_RECORD_GRABBED],
+        []
+      );
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      const outcomes = res.body.history.map(h => h.outcome);
+      expect(outcomes).toContain('imported');
+      expect(outcomes).toContain('failed');
+      expect(res.body.history).toHaveLength(2);
+    });
+  });
+
+  describe('tag filtering', () => {
+    it('only returns records tagged for the current user', async () => {
+      const app = createApp({ skipRateLimits: true });
+      setHistory([SONARR_RECORD_IMPORTED], []);
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      expect(res.body.history).toHaveLength(1);
+      expect(res.body.history[0].seriesName).toBe('My Show');
+      expect(res.body.history[0].outcome).toBe('imported');
+      expect(res.body.history[0].quality).toBe('720p');
+    });
+
+    it('excludes records tagged for a different user', async () => {
+      const app = createApp({ skipRateLimits: true });
+      const bobAuth = { AccessToken: 'tok3', User: { Id: 'uid3', Name: 'bob' } };
+      const bobUser = { Id: 'uid3', Name: 'bob', Policy: { IsAdministrator: false } };
+      setHistory([SONARR_RECORD_IMPORTED], []);
+      const { cookies } = await loginAs(app, bobUser, bobAuth);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      expect(res.body.history).toHaveLength(0);
+    });
+  });
+
+  describe('radarr records', () => {
+    it('returns movie history items', async () => {
+      const app = createApp({ skipRateLimits: true });
+      cache.set('poll:radarr-tags', [{ id: 1, label: 'alice' }], 60000);
+      setHistory([], [RADARR_RECORD_IMPORTED]);
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      expect(res.body.history).toHaveLength(1);
+      expect(res.body.history[0].type).toBe('movie');
+      expect(res.body.history[0].movieName).toBe('My Movie');
+    });
+  });
+
+  describe('?days parameter', () => {
+    it('uses custom days value', async () => {
+      const app = createApp({ skipRateLimits: true });
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent?days=14')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      expect(res.body.days).toBe(14);
+    });
+
+    it('caps days at 90', async () => {
+      const app = createApp({ skipRateLimits: true });
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent?days=999')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      expect(res.body.days).toBe(7); // falls back to default when > 90
+    });
+  });
+
+  describe('failed import details', () => {
+    it('includes failureMessage for admin on failed records', async () => {
+      const app = createApp({ skipRateLimits: true });
+      cache.set('poll:sonarr-tags', [{ data: SONARR_TAGS_WITH_ADMIN }], 60000);
+      setHistory([SONARR_RECORD_FAILED], []);
+      const { cookies } = await loginAs(app, EMBY_ADMIN, EMBY_AUTH_ADMIN);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      const failed = res.body.history.find(h => h.outcome === 'failed');
+      expect(failed).toBeDefined();
+      expect(failed.failureMessage).toBe('Not enough disk space');
+    });
+  });
+
+  describe('deduplication', () => {
+    it('suppresses a failed record when the same episode was subsequently imported', async () => {
+      const app = createApp({ skipRateLimits: true });
+      // API returns newest-first: imported (now) before failed (1hr ago)
+      setHistory([SONARR_RECORD_IMPORTED_EP55, SONARR_RECORD_FAILED_EP55], []);
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      const ep55Items = res.body.history.filter(h => h.seriesName === 'My Show' && h.title.includes('S02E01'));
+      expect(ep55Items).toHaveLength(1);
+      expect(ep55Items[0].outcome).toBe('imported');
+    });
+
+    it('shows a failed record as-is when there is no successful import and hasFile is false', async () => {
+      const app = createApp({ skipRateLimits: true });
+      setHistory([SONARR_RECORD_FAILED_EP56], []);
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      const item = res.body.history.find(h => h.title && h.title.includes('S02E02'));
+      expect(item).toBeDefined();
+      expect(item.outcome).toBe('failed');
+      expect(item.availableForUpgrade).toBeFalsy();
+    });
+
+    it('flags a failed record as availableForUpgrade when the episode hasFile is true', async () => {
+      const app = createApp({ skipRateLimits: true });
+      setHistory([SONARR_RECORD_FAILED_EP57_HAS_FILE], []);
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      const item = res.body.history.find(h => h.title && h.title.includes('S02E03'));
+      expect(item).toBeDefined();
+      expect(item.outcome).toBe('failed');
+      expect(item.availableForUpgrade).toBe(true);
+    });
+
+    it('does not expose _contentId in the response', async () => {
+      const app = createApp({ skipRateLimits: true });
+      setHistory([SONARR_RECORD_IMPORTED_EP55], []);
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      for (const item of res.body.history) {
+        expect(item).not.toHaveProperty('_contentId');
+      }
+    });
+  });
+
+  describe('response shape', () => {
+    it('returns correct top-level fields', async () => {
+      const app = createApp({ skipRateLimits: true });
+      const { cookies } = await loginAs(app);
+      const res = await request(app)
+        .get('/api/history/recent')
+        .set('Cookie', cookies);
+      expect(res.status).toBe(200);
+      expect(res.body).toHaveProperty('user');
+      expect(res.body).toHaveProperty('isAdmin');
+      expect(res.body).toHaveProperty('days');
+      expect(res.body).toHaveProperty('history');
+      expect(Array.isArray(res.body.history)).toBe(true);
+    });
+  });
+});

tests/setup.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 import { vi, beforeEach, afterEach } from 'vitest';
 import os from 'os';
 import path from 'path';

tests/unit/clients/DownloadClient.test.js

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const DownloadClient = require('../../../server/clients/DownloadClient');
+
+describe('DownloadClient', () => {
+  describe('Abstract Base Class', () => {
+    it('should throw error when instantiated directly', () => {
+      expect(() => {
+        new DownloadClient({ id: 'test', name: 'Test', url: 'http://test.com' });
+      }).toThrow('DownloadClient is an abstract class and cannot be instantiated directly');
+    });
+
+    it('should enforce implementation of required methods', () => {
+      class TestClient extends DownloadClient {
+        getClientType() {
+          return 'test';
+        }
+      }
+
+      const client = new TestClient({ id: 'test', name: 'Test', url: 'http://test.com' });
+      
+      expect(() => client.testConnection()).rejects.toThrow('testConnection() must be implemented by subclass');
+      expect(() => client.getActiveDownloads()).rejects.toThrow('getActiveDownloads() must be implemented by subclass');
+      expect(() => client.normalizeDownload({})).toThrow('normalizeDownload() must be implemented by subclass');
+    });
+  });
+
+  describe('Base Properties', () => {
+    class TestClient extends DownloadClient {
+      getClientType() {
+        return 'test';
+      }
+      
+      async testConnection() {
+        return true;
+      }
+      
+      async getActiveDownloads() {
+        return [];
+      }
+      
+      normalizeDownload(download) {
+        return download;
+      }
+    }
+
+    it('should set basic properties from config', () => {
+      const config = {
+        id: 'test-instance',
+        name: 'Test Instance',
+        url: 'http://test.com',
+        apiKey: 'test-key',
+        username: 'test-user',
+        password: 'test-pass'
+      };
+
+      const client = new TestClient(config);
+      
+      expect(client.id).toBe('test-instance');
+      expect(client.name).toBe('Test Instance');
+      expect(client.url).toBe('http://test.com');
+      expect(client.apiKey).toBe('test-key');
+      expect(client.username).toBe('test-user');
+      expect(client.password).toBe('test-pass');
+    });
+
+    it('should return correct instance ID', () => {
+      const client = new TestClient({ id: 'test-id', name: 'Test', url: 'http://test.com' });
+      expect(client.getInstanceId()).toBe('test-id');
+    });
+
+    it('should have optional getClientStatus method returning null', async () => {
+      const client = new TestClient({ id: 'test', name: 'Test', url: 'http://test.com' });
+      const status = await client.getClientStatus();
+      expect(status).toBeNull();
+    });
+  });
+});

tests/unit/clients/QBittorrentClient.test.js

@@ -0,0 +1,208 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+import QBittorrentClient from '../../../server/clients/QBittorrentClient.js';
+import nock from 'nock';
+import { vi } from 'vitest';
+
+vi.mock('../../../server/utils/logger', () => ({
+  logToFile: vi.fn()
+}));
+
+describe('QBittorrentClient', () => {
+  let client;
+  let mockConfig;
+
+  beforeEach(() => {
+    mockConfig = {
+      id: 'test-qb',
+      name: 'Test qBittorrent',
+      url: 'http://localhost:8080',
+      username: 'admin',
+      password: 'adminadmin'
+    };
+    
+    client = new QBittorrentClient(mockConfig);
+
+    // Clear all mocks
+    vi.clearAllMocks();
+  });
+
+  describe('Constructor', () => {
+    it('should initialize with correct properties', () => {
+      expect(client.getClientType()).toBe('qbittorrent');
+      expect(client.getInstanceId()).toBe('test-qb');
+      expect(client.name).toBe('Test qBittorrent');
+      expect(client.url).toBe('http://localhost:8080');
+      expect(client.authCookie).toBeNull();
+      expect(client.lastRid).toBe(0);
+      expect(client.torrentMap).toBeInstanceOf(Map);
+      expect(client.fallbackThisCycle).toBe(false);
+    });
+  });
+
+  describe('Authentication', () => {
+    it('should login successfully with valid credentials', async () => {
+      nock('http://localhost:8080')
+        .post('/api/v2/auth/login', 'username=admin&password=adminadmin')
+        .reply(200, {}, { 'set-cookie': ['SID=test-cookie'] });
+      
+      const result = await client.login();
+      
+      expect(result).toBe(true);
+      expect(client.authCookie).toBe('SID=test-cookie');
+    });
+
+    it('should handle login failure', async () => {
+      nock('http://localhost:8080')
+        .post('/api/v2/auth/login', 'username=admin&password=adminadmin')
+        .reply(200, {}, {});
+      
+      const result = await client.login();
+      
+      expect(result).toBe(false);
+      expect(client.authCookie).toBeNull();
+    });
+
+    it('should handle login error', async () => {
+      nock('http://localhost:8080')
+        .post('/api/v2/auth/login', 'username=admin&password=adminadmin')
+        .replyWithError(new Error('Network error'));
+      
+      const result = await client.login();
+      
+      expect(result).toBe(false);
+      expect(client.authCookie).toBeNull();
+    });
+  });
+
+  describe('Connection Test', () => {
+    it('should test connection successfully', async () => {
+      // Mock login success
+      client.login = vi.fn().mockResolvedValue(true);
+
+      // Mock version request
+      const mockResponse = { data: 'v4.3.5' };
+      client.makeRequest = vi.fn().mockResolvedValue(mockResponse);
+      
+      const result = await client.testConnection();
+      
+      expect(result).toBe(true);
+      expect(client.makeRequest).toHaveBeenCalledWith('/api/v2/app/version');
+    });
+
+    it('should handle connection test failure', async () => {
+      client.login = vi.fn().mockRejectedValue(new Error('Auth failed'));
+      
+      const result = await client.testConnection();
+      
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('Download Normalization', () => {
+    it('should normalize torrent data correctly', () => {
+      const torrent = {
+        hash: 'abc123',
+        name: 'Test Torrent',
+        state: 'downloading',
+        progress: 0.75,
+        size: 1000000000,
+        completed: 750000000,
+        dlspeed: 1048576,
+        eta: 3600,
+        category: 'movies',
+        tags: 'movie,hd',
+        content_path: '/downloads/test',
+        added_on: 1640995200
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized).toEqual({
+        id: 'abc123',
+        title: 'Test Torrent',
+        type: 'torrent',
+        client: 'qbittorrent',
+        instanceId: 'test-qb',
+        instanceName: 'Test qBittorrent',
+        status: 'Downloading',
+        progress: 75,
+        size: 1000000000,
+        downloaded: 750000000,
+        speed: 1048576,
+        eta: 3600,
+        category: 'movies',
+        tags: ['movie', 'hd'],
+        savePath: '/downloads/test',
+        addedOn: '2022-01-01T00:00:00.000Z',
+        raw: torrent
+      });
+    });
+
+    it('should handle unknown torrent states', () => {
+      const torrent = {
+        hash: 'abc123',
+        name: 'Test Torrent',
+        state: 'unknown_state',
+        progress: 0.5,
+        size: 1000000,
+        completed: 500000,
+        dlspeed: 0,
+        eta: -1
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized.status).toBe('unknown_state');
+      expect(normalized.eta).toBeNull();
+    });
+
+    it('should handle missing completed field', () => {
+      const torrent = {
+        hash: 'abc123',
+        name: 'Test Torrent',
+        state: 'downloading',
+        progress: 0.5,
+        size: 1000000,
+        dlspeed: 0
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized.downloaded).toBe(500000);
+    });
+  });
+
+  describe('Fallback Flag Management', () => {
+    it('should reset fallback flag', () => {
+      client.fallbackThisCycle = true;
+      client.resetFallbackFlag();
+      expect(client.fallbackThisCycle).toBe(false);
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle makeRequest authentication failure', async () => {
+      client.authCookie = 'invalid-cookie';
+      
+      // First request fails with 403
+      nock('http://localhost:8080')
+        .get('/test')
+        .reply(403, {});
+
+      // Re-authentication succeeds
+      nock('http://localhost:8080')
+        .post('/api/v2/auth/login', 'username=admin&password=adminadmin')
+        .reply(200, {}, { 'set-cookie': ['SID=new-cookie'] });
+
+      // Retry succeeds
+      nock('http://localhost:8080')
+        .get('/test')
+        .reply(200, { data: 'success' });
+      
+      const result = await client.makeRequest('/test');
+      
+      expect(result.data).toEqual({ data: 'success' });
+      expect(client.authCookie).toBe('SID=new-cookie');
+    });
+  });
+});

tests/unit/clients/RTorrentClient.test.js

@@ -0,0 +1,423 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+import RTorrentClient from '../../../server/clients/RTorrentClient.js';
+import { vi } from 'vitest';
+
+vi.mock('../../../server/utils/logger', () => ({
+  logToFile: vi.fn()
+}));
+
+describe('RTorrentClient', () => {
+  let client;
+  let mockConfig;
+  let mockMethodCall;
+
+  beforeEach(() => {
+    mockMethodCall = vi.fn();
+
+    mockConfig = {
+      id: 'test-rtorrent',
+      name: 'Test rTorrent',
+      url: 'http://localhost:8080',
+      username: 'rtorrent',
+      password: 'rtorrent'
+    };
+
+    client = new RTorrentClient(mockConfig);
+    // Mock the xmlrpc client's methodCall directly
+    client.client.methodCall = mockMethodCall;
+  });
+
+  describe('Constructor', () => {
+    it('should initialize with correct properties', () => {
+      expect(client.getClientType()).toBe('rtorrent');
+      expect(client.getInstanceId()).toBe('test-rtorrent');
+      expect(client.name).toBe('Test rTorrent');
+      expect(client.url).toBe('http://localhost:8080');
+    });
+
+    it('should create xmlrpc client with correct URL', async () => {
+      expect(client.url).toBe('http://localhost:8080');
+      expect(client.client).toBeDefined();
+    });
+
+    it('should create xmlrpc client without auth when no credentials', () => {
+      const noAuthConfig = {
+        id: 'test-rtorrent-noauth',
+        name: 'Test rTorrent No Auth',
+        url: 'http://localhost:8080/RPC2'
+      };
+      const clientNoAuth = new RTorrentClient(noAuthConfig);
+      expect(clientNoAuth.client).toBeDefined();
+    });
+
+    it('should use whatbox.ca-style /xmlrpc path exactly as configured', () => {
+      const whatboxConfig = {
+        id: 'test-whatbox',
+        name: 'Whatbox',
+        url: 'https://user.whatbox.ca/xmlrpc',
+        username: 'user',
+        password: 'pass'
+      };
+      const clientWhatbox = new RTorrentClient(whatboxConfig);
+      expect(clientWhatbox.client).toBeDefined();
+    });
+
+    it('should use custom RPC path exactly as configured', () => {
+      const customConfig = {
+        id: 'test-custom',
+        name: 'Custom',
+        url: 'https://example.com/custom/rpc/path'
+      };
+      const clientCustom = new RTorrentClient(customConfig);
+      expect(clientCustom.client).toBeDefined();
+    });
+  });
+
+  describe('Connection Test', () => {
+    it('should test connection successfully', async () => {
+      mockMethodCall.mockImplementation((method, params, callback) => {
+        callback(null, '0.9.8');
+      });
+
+      const result = await client.testConnection();
+
+      expect(result).toBe(true);
+    });
+
+    it('should handle connection test failure', async () => {
+      mockMethodCall.mockImplementation((method, params, callback) => {
+        callback(new Error('Connection refused'));
+      });
+
+      const result = await client.testConnection();
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('getActiveDownloads', () => {
+    it('should fetch and normalize torrents', async () => {
+      const mockTorrents = [
+        [
+          'abc123def456',
+          'Test Torrent 1',
+          1000000000,
+          750000000,
+          1048576,
+          0,
+          1,
+          1,
+          0,
+          '/downloads/test',
+          'movies'
+        ],
+        [
+          'def789abc012',
+          'Test Torrent 2',
+          2000000000,
+          2000000000,
+          0,
+          512000,
+          1,
+          1,
+          0,
+          '/downloads/complete',
+          'tv'
+        ]
+      ];
+
+      mockMethodCall.mockImplementation((method, params, callback) => {
+        callback(null, mockTorrents);
+      });
+
+      const downloads = await client.getActiveDownloads();
+
+      expect(downloads).toHaveLength(2);
+      expect(downloads[0].id).toBe('abc123def456');
+      expect(downloads[0].title).toBe('Test Torrent 1');
+      expect(downloads[0].status).toBe('Downloading');
+      expect(downloads[0].progress).toBe(75);
+      expect(downloads[0].category).toBe('movies');
+      expect(downloads[1].status).toBe('Seeding');
+      expect(downloads[1].category).toBe('tv');
+    });
+
+    it('should handle empty torrent list', async () => {
+      mockMethodCall.mockImplementation((method, params, callback) => {
+        callback(null, []);
+      });
+
+      const downloads = await client.getActiveDownloads();
+
+      expect(downloads).toEqual([]);
+    });
+
+    it('should handle XML-RPC errors gracefully', async () => {
+      mockMethodCall.mockImplementation((method, params, callback) => {
+        callback(new Error('XML-RPC fault'));
+      });
+
+      const downloads = await client.getActiveDownloads();
+
+      expect(downloads).toEqual([]);
+    });
+  });
+
+  describe('normalizeDownload', () => {
+    it('should normalize a downloading torrent', () => {
+      const torrent = [
+        'hash123',
+        'Downloading Torrent',
+        1000000000,
+        500000000,
+        1048576,
+        0,
+        1,
+        1,
+        0,
+        '/downloads',
+        ''
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized).toEqual({
+        id: 'hash123',
+        title: 'Downloading Torrent',
+        type: 'torrent',
+        client: 'rtorrent',
+        instanceId: 'test-rtorrent',
+        instanceName: 'Test rTorrent',
+        status: 'Downloading',
+        progress: 50,
+        size: 1000000000,
+        downloaded: 500000000,
+        speed: 1048576,
+        eta: 477,
+        category: undefined,
+        tags: [],
+        savePath: '/downloads',
+        addedOn: undefined,
+        arrQueueId: undefined,
+        arrType: undefined,
+        raw: torrent
+      });
+    });
+
+    it('should normalize a seeding torrent', () => {
+      const torrent = [
+        'hash456',
+        'Seeding Torrent',
+        500000000,
+        500000000,
+        0,
+        204800,
+        1,
+        1,
+        0,
+        '/downloads/complete',
+        'movies'
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized.status).toBe('Seeding');
+      expect(normalized.progress).toBe(100);
+      expect(normalized.speed).toBe(204800);
+      expect(normalized.eta).toBeNull();
+      expect(normalized.category).toBe('movies');
+      expect(normalized.tags).toEqual(['movies']);
+    });
+
+    it('should normalize a paused torrent', () => {
+      const torrent = [
+        'hash789',
+        'Paused Torrent',
+        1000000000,
+        250000000,
+        0,
+        0,
+        1,
+        0,
+        0,
+        '/downloads',
+        ''
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized.status).toBe('Paused');
+      expect(normalized.speed).toBe(0);
+      expect(normalized.eta).toBeNull();
+    });
+
+    it('should normalize a stopped torrent', () => {
+      const torrent = [
+        'hashabc',
+        'Stopped Torrent',
+        1000000000,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        '/downloads',
+        ''
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized.status).toBe('Stopped');
+    });
+
+    it('should normalize a checking torrent', () => {
+      const torrent = [
+        'hashdef',
+        'Checking Torrent',
+        1000000000,
+        500000000,
+        0,
+        0,
+        1,
+        0,
+        1,
+        '/downloads',
+        ''
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized.status).toBe('Checking');
+    });
+
+    it('should handle zero-size torrent', () => {
+      const torrent = [
+        'hash000',
+        'Zero Size',
+        0,
+        0,
+        0,
+        0,
+        1,
+        1,
+        0,
+        '/downloads',
+        ''
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized.progress).toBe(0);
+      expect(normalized.size).toBe(0);
+      expect(normalized.downloaded).toBe(0);
+    });
+  });
+
+  describe('Status Mapping', () => {
+    const testCases = [
+      { state: 0, isActive: 0, isHashChecking: 0, completed: 0, size: 100, expected: 'Stopped' },
+      { state: 1, isActive: 1, isHashChecking: 0, completed: 50, size: 100, expected: 'Downloading' },
+      { state: 1, isActive: 1, isHashChecking: 0, completed: 100, size: 100, expected: 'Seeding' },
+      { state: 1, isActive: 0, isHashChecking: 0, completed: 50, size: 100, expected: 'Paused' },
+      { state: 1, isActive: 0, isHashChecking: 0, completed: 100, size: 100, expected: 'Paused' },
+      { state: 1, isActive: 0, isHashChecking: 1, completed: 50, size: 100, expected: 'Checking' },
+      { state: 1, isActive: 1, isHashChecking: 1, completed: 50, size: 100, expected: 'Checking' }
+    ];
+
+    testCases.forEach(({ state, isActive, isHashChecking, completed, size, expected }) => {
+      it(`should map state=${state} isActive=${isActive} isHashChecking=${isHashChecking} to ${expected}`, () => {
+        const status = client._mapStatus(state, isActive, isHashChecking, completed, size);
+        expect(status).toBe(expected);
+      });
+    });
+  });
+
+  describe('ARR Info Extraction', () => {
+    it('should extract series info from filename', () => {
+      const torrent = [
+        'hash123',
+        'Show Name - S01E02 - Episode Title',
+        1000000000,
+        500000000,
+        1048576,
+        0,
+        1,
+        1,
+        0,
+        '/downloads',
+        ''
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+      expect(normalized.arrType).toBe('series');
+    });
+
+    it('should extract movie info from filename', () => {
+      const torrent = [
+        'hash456',
+        'Movie Title (2023) 1080p',
+        2000000000,
+        1000000000,
+        1048576,
+        0,
+        1,
+        1,
+        0,
+        '/downloads',
+        ''
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+      expect(normalized.arrType).toBe('movie');
+    });
+
+    it('should not extract ARR info from generic filename', () => {
+      const torrent = [
+        'hash789',
+        'Generic File Name.mkv',
+        1000000000,
+        500000000,
+        1048576,
+        0,
+        1,
+        1,
+        0,
+        '/downloads',
+        ''
+      ];
+
+      const normalized = client.normalizeDownload(torrent);
+      expect(normalized.arrType).toBeUndefined();
+    });
+  });
+
+  describe('Client Status', () => {
+    it('should get client status', async () => {
+      mockMethodCall.mockImplementation((method, params, callback) => {
+        if (method === 'throttle.global_down.rate') {
+          callback(null, 1048576);
+        } else if (method === 'throttle.global_up.rate') {
+          callback(null, 512000);
+        }
+      });
+
+      const status = await client.getClientStatus();
+
+      expect(status).toEqual({
+        globalDownRate: 1048576,
+        globalUpRate: 512000
+      });
+    });
+
+    it('should handle status request errors', async () => {
+      mockMethodCall.mockImplementation((method, params, callback) => {
+        callback(new Error('Status error'));
+      });
+
+      const status = await client.getClientStatus();
+
+      expect(status).toBeNull();
+    });
+  });
+});

tests/unit/clients/SABnzbdClient.test.js

@@ -0,0 +1,302 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+import SABnzbdClient from '../../../server/clients/SABnzbdClient.js';
+import nock from 'nock';
+import { vi } from 'vitest';
+vi.mock('../../../server/utils/logger', () => ({
+  logToFile: vi.fn()
+}));
+
+describe('SABnzbdClient', () => {
+  let client;
+  let mockConfig;
+
+  beforeEach(() => {
+    mockConfig = {
+      id: 'test-sab',
+      name: 'Test SABnzbd',
+      url: 'http://localhost:8080',
+      apiKey: 'test-api-key'
+    };
+    
+    client = new SABnzbdClient(mockConfig);
+    
+    // Clear all mocks
+    vi.clearAllMocks();
+  });
+
+  describe('Constructor', () => {
+    it('should initialize with correct properties', () => {
+      expect(client.getClientType()).toBe('sabnzbd');
+      expect(client.getInstanceId()).toBe('test-sab');
+      expect(client.name).toBe('Test SABnzbd');
+      expect(client.url).toBe('http://localhost:8080');
+      expect(client.apiKey).toBe('test-api-key');
+    });
+  });
+
+  describe('Connection Test', () => {
+    it('should test connection successfully', async () => {
+      const mockResponse = {
+        data: { version: '3.6.1' }
+      };
+      
+      client.makeRequest = vi.fn().mockResolvedValue(mockResponse);
+      
+      const result = await client.testConnection();
+      
+      expect(result).toBe(true);
+      expect(client.makeRequest).toHaveBeenCalledWith('', { mode: 'version' });
+    });
+
+    it('should handle connection test failure', async () => {
+      client.makeRequest = vi.fn().mockRejectedValue(new Error('Connection failed'));
+      
+      const result = await client.testConnection();
+      
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('API Requests', () => {
+    it('should make API request with correct parameters', async () => {
+      nock('http://localhost:8080')
+        .get('/api')
+        .query({
+          output: 'json',
+          apikey: 'test-api-key',
+          mode: 'queue',
+          limit: 10
+        })
+        .reply(200, { result: 'success' });
+      
+      const result = await client.makeRequest({ mode: 'queue', limit: 10 });
+      
+      expect(result.data).toEqual({ result: 'success' });
+    });
+
+    it('should handle API request errors', async () => {
+      nock('http://localhost:8080')
+        .get('/api')
+        .query({ output: 'json', apikey: 'test-api-key', mode: 'queue' })
+        .replyWithError(new Error('API Error'));
+      
+      await expect(client.makeRequest({ mode: 'queue' })).rejects.toThrow('API Error');
+    });
+  });
+
+  describe('Download Normalization', () => {
+    it('should normalize queue download correctly', () => {
+      const slot = {
+        nzo_id: 'test123',
+        filename: 'Test Movie.mkv',
+        status: 'Downloading',
+        progress: 75.5,
+        mb: 1000,
+        mbleft: 245,
+        kbpersec: 1024,
+        timeleft: '0:15:30',
+        cat: 'movies',
+        labels: 'movie,hd',
+        added: 1640995200
+      };
+
+      const normalized = client.normalizeDownload(slot, 'queue');
+
+      expect(normalized).toEqual({
+        id: 'test123',
+        title: 'Test Movie.mkv',
+        type: 'usenet',
+        client: 'sabnzbd',
+        instanceId: 'test-sab',
+        instanceName: 'Test SABnzbd',
+        status: 'Downloading',
+        progress: 76,
+        size: 1000 * 1024 * 1024,
+        downloaded: 755 * 1024 * 1024,
+        speed: 1024 * 1024,
+        eta: 930, // 15 minutes 30 seconds
+        category: 'movies',
+        tags: ['movie', 'hd'],
+        savePath: undefined,
+        addedOn: '2022-01-01T00:00:00.000Z',
+        raw: { ...slot, source: 'queue' }
+      });
+    });
+
+    it('should normalize history download correctly', () => {
+      const slot = {
+        nzo_id: 'test456',
+        filename: 'Test Series S01E01.mkv',
+        status: 'Completed',
+        mb: 500,
+        mbleft: 0,
+        cat: 'tv',
+        added: 1640995200
+      };
+
+      const normalized = client.normalizeDownload(slot, 'history');
+
+      expect(normalized.status).toBe('Completed');
+      expect(normalized.progress).toBe(100);
+      expect(normalized.downloaded).toBe(500 * 1024 * 1024);
+      expect(normalized.speed).toBe(0);
+      expect(normalized.eta).toBeNull();
+      expect(normalized.raw.source).toBe('history');
+    });
+
+    it('should parse time strings correctly', () => {
+      const testCases = [
+        { input: '0:05:30', expected: 330 },     // 5m 30s
+        { input: '15:30', expected: 930 },       // 15m 30s
+        { input: '330', expected: 330 },         // 330 seconds
+        { input: 'unknown', expected: null },    // unknown
+        { input: '0:00', expected: null }        // zero
+      ];
+
+      testCases.forEach(({ input, expected }) => {
+        const slot = {
+          nzo_id: 'test',
+          filename: 'Test',
+          status: 'Downloading',
+          progress: 50,
+          mb: 1000,
+          mbleft: 500,
+          timeleft: input
+        };
+
+        const normalized = client.normalizeDownload(slot, 'queue');
+        expect(normalized.eta).toBe(expected);
+      });
+    });
+
+    it('should extract Sonarr/Radarr info from filename', () => {
+      const testCases = [
+        { filename: 'Show Name - S01E02 - Episode Title', expectedType: 'series' },
+        { filename: 'Movie Title (2023) 1080p', expectedType: 'movie' },
+        { filename: 'Random File Name.mkv', expectedType: undefined }
+      ];
+
+      testCases.forEach(({ filename, expectedType }) => {
+        const slot = {
+          nzo_id: 'test',
+          filename: filename,
+          status: 'Downloading',
+          progress: 50,
+          mb: 1000,
+          mbleft: 500
+        };
+
+        const normalized = client.normalizeDownload(slot, 'queue');
+        expect(normalized.arrType).toBe(expectedType);
+      });
+    });
+
+    it('should handle size parsing from strings', () => {
+      const slot = {
+        nzo_id: 'test',
+        filename: 'Test',
+        status: 'Downloading',
+        progress: 50,
+        size: '1.5 GB',
+        sizeleft: '0.75 GB'
+      };
+
+      const normalized = client.normalizeDownload(slot, 'queue');
+      
+      expect(normalized.size).toBe(1.5 * 1024 * 1024 * 1024);
+      expect(normalized.downloaded).toBe(0.75 * 1024 * 1024 * 1024);
+      expect(normalized.progress).toBe(50);
+    });
+  });
+
+  describe('Unit Multipliers', () => {
+    it('should return correct multipliers for different units', () => {
+      expect(client.getUnitMultiplier('b')).toBe(1);
+      expect(client.getUnitMultiplier('KB')).toBe(1024);
+      expect(client.getUnitMultiplier('mb')).toBe(1024 * 1024);
+      expect(client.getUnitMultiplier('GB')).toBe(1024 * 1024 * 1024);
+      expect(client.getUnitMultiplier('tb')).toBe(1024 * 1024 * 1024 * 1024);
+      expect(client.getUnitMultiplier('unknown')).toBe(1);
+    });
+  });
+
+  describe('Active Downloads', () => {
+    it('should fetch and normalize downloads from queue and history', async () => {
+      const mockQueueResponse = {
+        data: {
+          queue: {
+            slots: [
+              { nzo_id: 'queue1', filename: 'Queue Item', status: 'Downloading' }
+            ]
+          }
+        }
+      };
+
+      const mockHistoryResponse = {
+        data: {
+          history: {
+            slots: [
+              { nzo_id: 'hist1', filename: 'History Item', status: 'Completed' }
+            ]
+          }
+        }
+      };
+
+      client.makeRequest = vi.fn()
+        .mockResolvedValueOnce(mockQueueResponse)
+        .mockResolvedValueOnce(mockHistoryResponse);
+
+      const downloads = await client.getActiveDownloads();
+
+      expect(client.makeRequest).toHaveBeenCalledWith({ mode: 'queue' });
+      expect(client.makeRequest).toHaveBeenCalledWith({ mode: 'history', limit: 10 });
+      expect(downloads).toHaveLength(2);
+      expect(downloads[0].id).toBe('queue1');
+      expect(downloads[1].id).toBe('hist1');
+    });
+
+    it('should handle API errors gracefully', async () => {
+      client.makeRequest = vi.fn().mockRejectedValue(new Error('API Error'));
+
+      const downloads = await client.getActiveDownloads();
+
+      expect(downloads).toEqual([]);
+    });
+  });
+
+  describe('Client Status', () => {
+    it('should get client status', async () => {
+      const mockResponse = {
+        data: {
+          queue: {
+            status: 'Active',
+            speed: 1048576,
+            kbpersec: 1024,
+            sizeleft: 500000000,
+            mbleft: 500
+          }
+        }
+      };
+
+      client.makeRequest = vi.fn().mockResolvedValue(mockResponse);
+
+      const status = await client.getClientStatus();
+
+      expect(status).toEqual({
+        status: 'Active',
+        speed: 1048576,
+        kbpersec: 1024,
+        sizeleft: 500000000,
+        mbleft: 500
+      });
+    });
+
+    it('should handle status request errors', async () => {
+      client.makeRequest = vi.fn().mockRejectedValue(new Error('Status error'));
+
+      const status = await client.getClientStatus();
+
+      expect(status).toBeNull();
+    });
+  });
+});

tests/unit/clients/TransmissionClient.test.js

@@ -0,0 +1,436 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+import TransmissionClient from '../../../server/clients/TransmissionClient.js';
+import nock from 'nock';
+import { vi } from 'vitest';
+
+vi.mock('../../../server/utils/logger', () => ({
+  logToFile: vi.fn()
+}));
+
+describe('TransmissionClient', () => {
+  let client;
+  let mockConfig;
+
+  beforeEach(() => {
+    mockConfig = {
+      id: 'test-transmission',
+      name: 'Test Transmission',
+      url: 'http://localhost:9091',
+      username: 'transmission',
+      password: 'transmission'
+    };
+    
+    client = new TransmissionClient(mockConfig);
+    
+    // Clear all mocks
+    vi.clearAllMocks();
+  });
+
+  describe('Constructor', () => {
+    it('should initialize with correct properties', () => {
+      expect(client.getClientType()).toBe('transmission');
+      expect(client.getInstanceId()).toBe('test-transmission');
+      expect(client.name).toBe('Test Transmission');
+      expect(client.url).toBe('http://localhost:9091');
+      expect(client.sessionId).toBeNull();
+      expect(client.rpcUrl).toBe('http://localhost:9091/transmission/rpc');
+    });
+  });
+
+  describe('Connection Test', () => {
+    it('should test connection successfully', async () => {
+      const mockResponse = {
+        data: { result: 'success', arguments: {} }
+      };
+      
+      client.makeRequest = vi.fn().mockResolvedValue(mockResponse);
+      
+      const result = await client.testConnection();
+      
+      expect(result).toBe(true);
+      expect(client.makeRequest).toHaveBeenCalledWith('session-get');
+    });
+
+    it('should handle connection test failure', async () => {
+      client.makeRequest = vi.fn().mockRejectedValue(new Error('Connection failed'));
+      
+      const result = await client.testConnection();
+      
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('RPC Requests', () => {
+    it('should make RPC request with session ID', async () => {
+      client.sessionId = 'test-session-id';
+      
+      nock('http://localhost:9091')
+        .post('/transmission/rpc', {
+          method: 'torrent-get',
+          arguments: { fields: ['id', 'name'] }
+        })
+        .reply(200, { result: 'success', arguments: { torrents: [] } });
+      
+      const result = await client.makeRequest('torrent-get', { fields: ['id', 'name'] });
+      
+      expect(result.data).toEqual({ result: 'success', arguments: { torrents: [] } });
+    });
+
+    it('should handle session ID conflict (409)', async () => {
+      nock('http://localhost:9091')
+        .post('/transmission/rpc', { method: 'session-get', arguments: {} })
+        .reply(409, {}, { 'x-transmission-session-id': 'new-session-id' });
+      
+      nock('http://localhost:9091')
+        .post('/transmission/rpc', { method: 'session-get', arguments: {} })
+        .reply(200, { result: 'success', arguments: {} });
+      
+      const result = await client.makeRequest('session-get');
+      
+      expect(client.sessionId).toBe('new-session-id');
+      expect(result.data).toEqual({ result: 'success', arguments: {} });
+    });
+
+    it('should handle RPC errors', async () => {
+      nock('http://localhost:9091')
+        .post('/transmission/rpc', { method: 'invalid-method', arguments: {} })
+        .reply(200, { result: 'error', 'error-message': 'Invalid request' });
+      
+      await expect(client.makeRequest('invalid-method')).rejects.toThrow('Transmission RPC error: error');
+    });
+  });
+
+  describe('Download Normalization', () => {
+    it('should normalize torrent data correctly', () => {
+      const torrent = {
+        id: 1,
+        hashString: 'abc123',
+        name: 'Test Torrent',
+        status: 4, // downloading
+        totalSize: 1000000000,
+        sizeWhenDone: 1000000000,
+        leftUntilDone: 250000000,
+        rateDownload: 1048576,
+        rateUpload: 0,
+        eta: 3600,
+        downloadedEver: 750000000,
+        uploadedEver: 0,
+        percentDone: 0.75,
+        addedDate: 1640995200,
+        doneDate: 0,
+        labels: ['movies', 'hd'],
+        downloadDir: '/downloads/test'
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+
+      expect(normalized).toEqual({
+        id: 'abc123',
+        title: 'Test Torrent',
+        type: 'torrent',
+        client: 'transmission',
+        instanceId: 'test-transmission',
+        instanceName: 'Test Transmission',
+        status: 'Downloading',
+        progress: 75,
+        size: 1000000000,
+        downloaded: 750000000,
+        speed: 1048576,
+        eta: 3600,
+        category: 'movies',
+        tags: ['movies', 'hd'],
+        savePath: '/downloads/test',
+        addedOn: '2022-01-01T00:00:00.000Z',
+        raw: torrent
+      });
+    });
+
+    it('should handle different torrent statuses', () => {
+      const statusMap = {
+        0: 'Stopped',
+        1: 'Queued',
+        2: 'Checking',
+        3: 'Queued',
+        4: 'Downloading',
+        5: 'Queued',
+        6: 'Seeding',
+        7: 'Unknown'
+      };
+
+      Object.entries(statusMap).forEach(([status, expectedStatus]) => {
+        const torrent = {
+          id: 1,
+          hashString: 'abc123',
+          name: 'Test',
+          status: parseInt(status),
+          totalSize: 1000000,
+          sizeWhenDone: 1000000,
+          leftUntilDone: 500000,
+          rateDownload: 0,
+          eta: -1,
+          percentDone: 0.5,
+          labels: []
+        };
+
+        const normalized = client.normalizeDownload(torrent);
+        expect(normalized.status).toBe(expectedStatus);
+      });
+    });
+
+    it('should handle unknown ETA values', () => {
+      const testCases = [
+        { eta: -1, expected: null },
+        { eta: -2, expected: null },
+        { eta: 3600, expected: 3600 }
+      ];
+
+      testCases.forEach(({ eta, expected }) => {
+        const torrent = {
+          id: 1,
+          hashString: 'abc123',
+          name: 'Test',
+          status: 4,
+          totalSize: 1000000,
+          sizeWhenDone: 1000000,
+          leftUntilDone: 500000,
+          rateDownload: 0,
+          eta: eta,
+          percentDone: 0.5,
+          labels: []
+        };
+
+        const normalized = client.normalizeDownload(torrent);
+        expect(normalized.eta).toBe(expected);
+      });
+    });
+
+    it('should extract category from first label', () => {
+      const torrent = {
+        id: 1,
+        hashString: 'abc123',
+        name: 'Test',
+        status: 4,
+        totalSize: 1000000,
+        sizeWhenDone: 1000000,
+        leftUntilDone: 500000,
+        rateDownload: 0,
+        eta: -1,
+        percentDone: 0.5,
+        labels: ['movies', 'hd', '4k']
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+      expect(normalized.category).toBe('movies');
+      expect(normalized.tags).toEqual(['movies', 'hd', '4k']);
+    });
+
+    it('should handle empty labels', () => {
+      const torrent = {
+        id: 1,
+        hashString: 'abc123',
+        name: 'Test',
+        status: 4,
+        totalSize: 1000000,
+        sizeWhenDone: 1000000,
+        leftUntilDone: 500000,
+        rateDownload: 0,
+        eta: -1,
+        percentDone: 0.5,
+        labels: []
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+      expect(normalized.category).toBeUndefined();
+      expect(normalized.tags).toEqual([]);
+    });
+  });
+
+  describe('Active Downloads', () => {
+    it('should fetch and normalize torrents', async () => {
+      const mockResponse = {
+        data: {
+          result: 'success',
+          arguments: {
+            torrents: [
+              {
+                id: 1,
+                hashString: 'abc123',
+                name: 'Test Torrent 1',
+                status: 4,
+                totalSize: 1000000,
+                sizeWhenDone: 1000000,
+                leftUntilDone: 500000,
+                rateDownload: 1048576,
+                eta: 3600,
+                percentDone: 0.5,
+                labels: ['test']
+              },
+              {
+                id: 2,
+                hashString: 'def456',
+                name: 'Test Torrent 2',
+                status: 6,
+                totalSize: 2000000,
+                sizeWhenDone: 2000000,
+                leftUntilDone: 0,
+                rateDownload: 0,
+                eta: -1,
+                percentDone: 1.0,
+                labels: []
+              }
+            ]
+          }
+        }
+      };
+
+      client.makeRequest = vi.fn().mockResolvedValue(mockResponse);
+
+      const downloads = await client.getActiveDownloads();
+
+      expect(client.makeRequest).toHaveBeenCalledWith('torrent-get', {
+        fields: [
+          'id', 'name', 'hashString', 'status', 'totalSize', 'sizeWhenDone',
+          'leftUntilDone', 'rateDownload', 'rateUpload', 'eta', 'downloadedEver',
+          'uploadedEver', 'percentDone', 'addedDate', 'doneDate', 'trackerStats',
+          'labels', 'downloadDir', 'error', 'errorString', 'peersConnected',
+          'peersGettingFromUs', 'peersSendingToUs', 'queuePosition'
+        ]
+      });
+
+      expect(downloads).toHaveLength(2);
+      expect(downloads[0].title).toBe('Test Torrent 1');
+      expect(downloads[0].status).toBe('Downloading');
+      expect(downloads[1].title).toBe('Test Torrent 2');
+      expect(downloads[1].status).toBe('Seeding');
+    });
+
+    it('should handle API errors gracefully', async () => {
+      client.makeRequest = vi.fn().mockRejectedValue(new Error('API Error'));
+
+      const downloads = await client.getActiveDownloads();
+
+      expect(downloads).toEqual([]);
+    });
+
+    it('should handle empty torrent list', async () => {
+      const mockResponse = {
+        data: {
+          result: 'success',
+          arguments: { torrents: [] }
+        }
+      };
+
+      client.makeRequest = vi.fn().mockResolvedValue(mockResponse);
+
+      const downloads = await client.getActiveDownloads();
+
+      expect(downloads).toEqual([]);
+    });
+  });
+
+  describe('Client Status', () => {
+    it('should get client status and session stats', async () => {
+      const mockSessionResponse = {
+        data: {
+          result: 'success',
+          arguments: {
+            'download-dir': '/downloads',
+            'peer-port': 51413,
+            'rpc-version': 15
+          }
+        }
+      };
+
+      const mockStatsResponse = {
+        data: {
+          result: 'success',
+          arguments: {
+            'downloaded-bytes': 1000000000,
+            'uploaded-bytes': 500000000,
+            'torrent-count': 5
+          }
+        }
+      };
+
+      client.makeRequest = vi.fn()
+        .mockResolvedValueOnce(mockSessionResponse)
+        .mockResolvedValueOnce(mockStatsResponse);
+
+      const status = await client.getClientStatus();
+
+      expect(client.makeRequest).toHaveBeenCalledWith('session-get');
+      expect(client.makeRequest).toHaveBeenCalledWith('session-stats');
+      expect(status).toEqual({
+        session: mockSessionResponse.data.arguments,
+        stats: mockStatsResponse.data.arguments
+      });
+    });
+
+    it('should handle status request errors', async () => {
+      client.makeRequest = vi.fn().mockRejectedValue(new Error('Status error'));
+
+      const status = await client.getClientStatus();
+
+      expect(status).toBeNull();
+    });
+  });
+
+  describe('ARR Info Extraction', () => {
+    it('should extract series info from filename', () => {
+      const torrent = {
+        id: 1,
+        hashString: 'abc123',
+        name: 'Show Name - S01E02 - Episode Title',
+        status: 4,
+        totalSize: 1000000,
+        sizeWhenDone: 1000000,
+        leftUntilDone: 500000,
+        rateDownload: 0,
+        eta: -1,
+        percentDone: 0.5,
+        labels: []
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+      expect(normalized.arrType).toBe('series');
+    });
+
+    it('should extract movie info from filename', () => {
+      const torrent = {
+        id: 1,
+        hashString: 'abc123',
+        name: 'Movie Title (2023) 1080p',
+        status: 4,
+        totalSize: 1000000,
+        sizeWhenDone: 1000000,
+        leftUntilDone: 500000,
+        rateDownload: 0,
+        eta: -1,
+        percentDone: 0.5,
+        labels: []
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+      expect(normalized.arrType).toBe('movie');
+    });
+
+    it('should not extract ARR info from generic filename', () => {
+      const torrent = {
+        id: 1,
+        hashString: 'abc123',
+        name: 'Generic File Name.mkv',
+        status: 4,
+        totalSize: 1000000,
+        sizeWhenDone: 1000000,
+        leftUntilDone: 500000,
+        rateDownload: 0,
+        eta: -1,
+        percentDone: 0.5,
+        labels: []
+      };
+
+      const normalized = client.normalizeDownload(torrent);
+      expect(normalized.arrType).toBeUndefined();
+    });
+  });
+});

tests/unit/config.test.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Tests for server/utils/config.js
  *

tests/unit/downloadClients.test.js

@@ -0,0 +1,347 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+import {
+  DownloadClientRegistry,
+  registry,
+  initializeClients,
+  getAllClients,
+  getClient,
+  getClientsByType,
+  getAllDownloads,
+  getDownloadsByClientType,
+  testAllConnections,
+  getAllClientStatuses
+} from '../../server/utils/downloadClients.js';
+import * as mockConfig from '../../server/utils/config.js';
+import { vi } from 'vitest';
+
+// Mock config and clients
+vi.mock('../../server/utils/config', () => ({
+  getSABnzbdInstances: vi.fn(),
+  getQbittorrentInstances: vi.fn(),
+  getTransmissionInstances: vi.fn(),
+  getRtorrentInstances: vi.fn()
+}));
+
+vi.mock('../../server/utils/logger', () => ({
+  logToFile: vi.fn()
+}));
+
+vi.mock('../../server/clients/SABnzbdClient', () => {
+  return vi.fn().mockImplementation((config) => ({
+    getClientType: () => 'sabnzbd',
+    getInstanceId: () => config.id,
+    name: config.name,
+    getActiveDownloads: vi.fn().mockResolvedValue([
+      { id: 'sab1', title: 'SAB Download 1', client: 'sabnzbd' }
+    ]),
+    testConnection: vi.fn().mockResolvedValue(true),
+    getClientStatus: vi.fn().mockResolvedValue({ status: 'active' })
+  }));
+});
+
+vi.mock('../../server/clients/QBittorrentClient', () => {
+  return vi.fn().mockImplementation((config) => ({
+    getClientType: () => 'qbittorrent',
+    getInstanceId: () => config.id,
+    name: config.name,
+    getActiveDownloads: vi.fn().mockResolvedValue([
+      { id: 'qb1', title: 'QB Download 1', client: 'qbittorrent' }
+    ]),
+    testConnection: vi.fn().mockResolvedValue(true),
+    getClientStatus: vi.fn().mockResolvedValue({ status: 'active' }),
+    resetFallbackFlag: vi.fn()
+  }));
+});
+
+vi.mock('../../server/clients/TransmissionClient', () => {
+  return vi.fn().mockImplementation((config) => ({
+    getClientType: () => 'transmission',
+    getInstanceId: () => config.id,
+    name: config.name,
+    getActiveDownloads: vi.fn().mockResolvedValue([
+      { id: 'trans1', title: 'Trans Download 1', client: 'transmission' }
+    ]),
+    testConnection: vi.fn().mockResolvedValue(true),
+    getClientStatus: vi.fn().mockResolvedValue({ status: 'active' })
+  }));
+});
+
+vi.mock('../../server/clients/RTorrentClient', () => {
+  return vi.fn().mockImplementation((config) => ({
+    getClientType: () => 'rtorrent',
+    getInstanceId: () => config.id,
+    name: config.name,
+    getActiveDownloads: vi.fn().mockResolvedValue([
+      { id: 'rt1', title: 'rTorrent Download 1', client: 'rtorrent' }
+    ]),
+    testConnection: vi.fn().mockResolvedValue(true),
+    getClientStatus: vi.fn().mockResolvedValue({ status: 'active' })
+  }));
+});
+
+describe('DownloadClientRegistry', () => {
+  let testRegistry;
+
+  beforeEach(() => {
+    testRegistry = new DownloadClientRegistry();
+    vi.clearAllMocks();
+  });
+
+  describe('Initialization', () => {
+    it('should initialize all configured client types', async () => {
+      // Manually add mock clients to the registry
+      const mockSabClient = {
+        getClientType: () => 'sabnzbd',
+        getInstanceId: () => 'sab1',
+        name: 'SAB 1'
+      };
+      const mockQbClient = {
+        getClientType: () => 'qbittorrent',
+        getInstanceId: () => 'qb1',
+        name: 'QB 1'
+      };
+      const mockTransClient = {
+        getClientType: () => 'transmission',
+        getInstanceId: () => 'trans1',
+        name: 'Trans 1'
+      };
+      testRegistry.clients.set('sab1', mockSabClient);
+      testRegistry.clients.set('qb1', mockQbClient);
+      testRegistry.clients.set('trans1', mockTransClient);
+
+      expect(testRegistry.getAllClients()).toHaveLength(3);
+      expect(testRegistry.getClient('sab1')).toBeTruthy();
+      expect(testRegistry.getClient('qb1')).toBeTruthy();
+      expect(testRegistry.getClient('trans1')).toBeTruthy();
+    });
+
+    it('should handle empty config', async () => {
+      // Registry is already empty from beforeEach
+      expect(testRegistry.getAllClients()).toHaveLength(0);
+    });
+
+    it('should not initialize twice', async () => {
+      // Manually set initialized flag to true
+      testRegistry.initialized = true;
+      
+      // Try to initialize again
+      await testRegistry.initialize();
+      
+      // Config should not be called since initialized is true
+      expect(mockConfig.getSABnzbdInstances).not.toHaveBeenCalled();
+    });
+
+    it('should handle client creation errors gracefully', async () => {
+      // Registry is already empty from beforeEach
+      expect(testRegistry.getAllClients()).toHaveLength(0);
+    });
+  });
+
+  describe('Client Management', () => {
+    beforeEach(async () => {
+      // Manually add mock client to the registry
+      const mockSabClient = {
+        getClientType: () => 'sabnzbd',
+        getInstanceId: () => 'sab1',
+        name: 'SAB 1',
+        testConnection: vi.fn().mockResolvedValue(true),
+        getActiveDownloads: vi.fn().mockResolvedValue([])
+      };
+      testRegistry.clients.set('sab1', mockSabClient);
+    });
+
+    it('should get all clients', () => {
+      const clients = testRegistry.getAllClients();
+      expect(clients).toHaveLength(1);
+      expect(clients[0].getClientType()).toBe('sabnzbd');
+    });
+
+    it('should get client by ID', () => {
+      const client = testRegistry.getClient('sab1');
+      expect(client).toBeTruthy();
+      expect(client.getInstanceId()).toBe('sab1');
+    });
+
+    it('should return null for non-existent client', () => {
+      const client = testRegistry.getClient('nonexistent');
+      expect(client).toBeNull();
+    });
+
+    it('should get clients by type', () => {
+      const sabClients = testRegistry.getClientsByType('sabnzbd');
+      expect(sabClients).toHaveLength(1);
+      
+      const qbClients = testRegistry.getClientsByType('qbittorrent');
+      expect(qbClients).toHaveLength(0);
+    });
+  });
+
+  describe('Download Management', () => {
+    beforeEach(async () => {
+      // Manually add mock clients to the registry
+      const mockSabClient = {
+        getClientType: () => 'sabnzbd',
+        getInstanceId: () => 'sab1',
+        name: 'SAB 1',
+        testConnection: vi.fn().mockResolvedValue(true),
+        getActiveDownloads: vi.fn().mockResolvedValue([
+          { id: 'sab1', title: 'SAB Download 1', client: 'sabnzbd' }
+ ])
+      };
+      const mockQbClient = {
+        getClientType: () => 'qbittorrent',
+        getInstanceId: () => 'qb1',
+        name: 'QB 1',
+        testConnection: vi.fn().mockResolvedValue(true),
+        getActiveDownloads: vi.fn().mockResolvedValue([
+          { id: 'qb1', title: 'QB Download 1', client: 'qbittorrent' }
+        ]),
+        resetFallbackFlag: vi.fn()
+      };
+      testRegistry.clients.set('sab1', mockSabClient);
+      testRegistry.clients.set('qb1', mockQbClient);
+    });
+
+    it('should get all downloads from all clients', async () => {
+      const downloads = await testRegistry.getAllDownloads();
+      
+      expect(downloads).toHaveLength(2);
+      expect(downloads[0].client).toBe('sabnzbd');
+      expect(downloads[1].client).toBe('qbittorrent');
+    });
+
+    it('should reset fallback flags for qBittorrent clients', async () => {
+      const qbClient = testRegistry.getClient('qb1');
+      
+      await testRegistry.getAllDownloads();
+      
+      expect(qbClient.resetFallbackFlag).toHaveBeenCalled();
+    });
+
+    it('should get downloads grouped by client type', async () => {
+      const downloadsByType = await testRegistry.getDownloadsByClientType();
+      
+      expect(downloadsByType.sabnzbd).toHaveLength(1);
+      expect(downloadsByType.qbittorrent).toHaveLength(1);
+      expect(downloadsByType.transmission).toBeUndefined();
+    });
+
+    it('should handle client errors gracefully', async () => {
+      const sabClient = testRegistry.getClient('sab1');
+      sabClient.getActiveDownloads.mockRejectedValue(new Error('Client error'));
+
+      const downloads = await testRegistry.getAllDownloads();
+      
+      expect(downloads).toHaveLength(1); // Only qBittorrent succeeds
+    });
+  });
+
+  describe('Connection Testing', () => {
+    beforeEach(async () => {
+      // Manually add mock clients to the registry
+      const mockSabClient = {
+        getClientType: () => 'sabnzbd',
+        getInstanceId: () => 'sab1',
+        name: 'SAB 1',
+        testConnection: vi.fn().mockResolvedValue(true),
+        getActiveDownloads: vi.fn().mockResolvedValue([])
+      };
+      const mockQbClient = {
+        getClientType: () => 'qbittorrent',
+        getInstanceId: () => 'qb1',
+        name: 'QB 1',
+        testConnection: vi.fn().mockResolvedValue(true),
+        getActiveDownloads: vi.fn().mockResolvedValue([])
+      };
+      testRegistry.clients.set('sab1', mockSabClient);
+      testRegistry.clients.set('qb1', mockQbClient);
+    });
+
+    it('should test all connections', async () => {
+      const results = await testRegistry.testAllConnections();
+      
+      expect(results).toHaveLength(2);
+      expect(results[0]).toEqual({
+        instanceId: 'sab1',
+        instanceName: 'SAB 1',
+        clientType: 'sabnzbd',
+        success: true,
+        error: null
+      });
+      expect(results[1]).toEqual({
+        instanceId: 'qb1',
+        instanceName: 'QB 1',
+        clientType: 'qbittorrent',
+        success: true,
+        error: null
+      });
+    });
+
+    it('should handle connection test failures', async () => {
+      const sabClient = testRegistry.getClient('sab1');
+      sabClient.testConnection.mockRejectedValue(new Error('Connection failed'));
+
+      const results = await testRegistry.testAllConnections();
+      
+      expect(results[0].success).toBe(false);
+      expect(results[0].error).toBe('Connection failed');
+    });
+  });
+
+  describe('Client Status', () => {
+    beforeEach(async () => {
+      // Manually add a mock client to the registry
+      const mockClient = {
+        getClientType: () => 'sabnzbd',
+        getInstanceId: () => 'sab1',
+        name: 'SAB 1',
+        getClientStatus: vi.fn().mockResolvedValue({ status: 'active' })
+      };
+      testRegistry.clients.set('sab1', mockClient);
+    });
+
+    it('should get all client statuses', async () => {
+      const statuses = await testRegistry.getAllClientStatuses();
+
+      expect(statuses).toHaveLength(1);
+      expect(statuses[0]).toEqual({
+        instanceId: 'sab1',
+        instanceName: 'SAB 1',
+        clientType: 'sabnzbd',
+        status: { status: 'active' }
+      });
+    });
+
+    it('should handle status request errors', async () => {
+      const sabClient = testRegistry.getClient('sab1');
+      sabClient.getClientStatus.mockRejectedValue(new Error('Status error'));
+
+      const statuses = await testRegistry.getAllClientStatuses();
+
+      expect(statuses[0].status).toBeNull();
+      expect(statuses[0].error).toBe('Status error');
+    });
+  });
+});
+
+describe('Convenience Functions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should delegate to singleton registry', async () => {
+    mockConfig.getSABnzbdInstances.mockReturnValue([]);
+    mockConfig.getQbittorrentInstances.mockReturnValue([]);
+    mockConfig.getTransmissionInstances.mockReturnValue([]);
+
+    await initializeClients();
+    
+    expect(getAllClients()).toBeInstanceOf(Array);
+    expect(getClient('test')).toBeNull();
+    expect(getClientsByType('sabnzbd')).toBeInstanceOf(Array);
+    expect(await getAllDownloads()).toBeInstanceOf(Array);
+    expect(await getDownloadsByClientType()).toBeInstanceOf(Object);
+    expect(await testAllConnections()).toBeInstanceOf(Array);
+    expect(await getAllClientStatuses()).toBeInstanceOf(Array);
+  });
+});

tests/unit/historyFetcher.test.js

@@ -0,0 +1,178 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+/**
+ * Unit tests for server/utils/historyFetcher.js
+ *
+ * Covers:
+ *  - classifySonarrEvent / classifyRadarrEvent event classification
+ *  - fetchSonarrHistory / fetchRadarrHistory: successful fetch, cache hit, per-instance errors
+ *  - invalidateHistoryCache
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import nock from 'nock';
+
+// Env must be set before importing modules that read it at load time
+process.env.SONARR_INSTANCES = JSON.stringify([
+  { id: 'sonarr-1', name: 'Main Sonarr', url: 'https://sonarr.test', apiKey: 'sonarr-key' }
+]);
+process.env.RADARR_INSTANCES = JSON.stringify([
+  { id: 'radarr-1', name: 'Main Radarr', url: 'https://radarr.test', apiKey: 'radarr-key' }
+]);
+
+const { classifySonarrEvent, classifyRadarrEvent, fetchSonarrHistory, fetchRadarrHistory, invalidateHistoryCache } =
+  await import('../../server/utils/historyFetcher.js');
+
+const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+
+afterEach(() => {
+  nock.cleanAll();
+  invalidateHistoryCache();
+});
+
+describe('classifySonarrEvent', () => {
+  it('returns imported for downloadFolderImported', () => {
+    expect(classifySonarrEvent('downloadFolderImported')).toBe('imported');
+  });
+  it('returns imported for downloadImported', () => {
+    expect(classifySonarrEvent('downloadImported')).toBe('imported');
+  });
+  it('returns failed for downloadFailed', () => {
+    expect(classifySonarrEvent('downloadFailed')).toBe('failed');
+  });
+  it('returns failed for importFailed', () => {
+    expect(classifySonarrEvent('importFailed')).toBe('failed');
+  });
+  it('returns other for grabbed', () => {
+    expect(classifySonarrEvent('grabbed')).toBe('other');
+  });
+  it('returns other for unknown event', () => {
+    expect(classifySonarrEvent('someFutureEvent')).toBe('other');
+  });
+});
+
+describe('classifyRadarrEvent', () => {
+  it('returns imported for downloadFolderImported', () => {
+    expect(classifyRadarrEvent('downloadFolderImported')).toBe('imported');
+  });
+  it('returns failed for downloadFailed', () => {
+    expect(classifyRadarrEvent('downloadFailed')).toBe('failed');
+  });
+  it('returns other for grabbed', () => {
+    expect(classifyRadarrEvent('grabbed')).toBe('other');
+  });
+});
+
+describe('fetchSonarrHistory', () => {
+  const mockRecords = [
+    {
+      id: 1,
+      eventType: 'downloadFolderImported',
+      sourceTitle: 'Show.S01E01',
+      date: new Date().toISOString(),
+      series: { id: 10, title: 'My Show', titleSlug: 'my-show', tags: [] },
+      seriesId: 10
+    }
+  ];
+
+  it('fetches records and tags them with _instanceUrl and _instanceName', async () => {
+    nock('https://sonarr.test')
+      .get('/api/v3/history')
+      .query(true)
+      .reply(200, { records: mockRecords });
+
+    const result = await fetchSonarrHistory(since);
+    expect(result).toHaveLength(1);
+    expect(result[0].series._instanceUrl).toBe('https://sonarr.test');
+    expect(result[0].series._instanceName).toBe('Main Sonarr');
+    expect(result[0]._instanceName).toBe('Main Sonarr');
+  });
+
+  it('returns cached data on second call without making a new HTTP request', async () => {
+    nock('https://sonarr.test')
+      .get('/api/v3/history')
+      .query(true)
+      .reply(200, { records: mockRecords });
+
+    const first = await fetchSonarrHistory(since);
+    // Second call — nock would throw if a second request was made
+    const second = await fetchSonarrHistory(since);
+    expect(second).toEqual(first);
+  });
+
+  it('returns empty array and does not throw when instance errors', async () => {
+    nock('https://sonarr.test')
+      .get('/api/v3/history')
+      .query(true)
+      .replyWithError('ECONNREFUSED');
+
+    const result = await fetchSonarrHistory(since);
+    expect(result).toEqual([]);
+  });
+
+  it('handles missing records key gracefully', async () => {
+    nock('https://sonarr.test')
+      .get('/api/v3/history')
+      .query(true)
+      .reply(200, {});
+
+    const result = await fetchSonarrHistory(since);
+    expect(result).toEqual([]);
+  });
+});
+
+describe('fetchRadarrHistory', () => {
+  const mockRecords = [
+    {
+      id: 2,
+      eventType: 'downloadFolderImported',
+      sourceTitle: 'My.Movie.2024',
+      date: new Date().toISOString(),
+      movie: { id: 20, title: 'My Movie', titleSlug: 'my-movie-2024', tags: [] },
+      movieId: 20
+    }
+  ];
+
+  it('fetches records and tags them with _instanceUrl and _instanceName', async () => {
+    nock('https://radarr.test')
+      .get('/api/v3/history')
+      .query(true)
+      .reply(200, { records: mockRecords });
+
+    const result = await fetchRadarrHistory(since);
+    expect(result).toHaveLength(1);
+    expect(result[0].movie._instanceUrl).toBe('https://radarr.test');
+    expect(result[0].movie._instanceName).toBe('Main Radarr');
+  });
+
+  it('returns empty array on network error', async () => {
+    nock('https://radarr.test')
+      .get('/api/v3/history')
+      .query(true)
+      .replyWithError('timeout');
+
+    const result = await fetchRadarrHistory(since);
+    expect(result).toEqual([]);
+  });
+});
+
+describe('invalidateHistoryCache', () => {
+  it('forces a fresh fetch after invalidation', async () => {
+    nock('https://sonarr.test')
+      .get('/api/v3/history')
+      .query(true)
+      .reply(200, { records: [] });
+
+    await fetchSonarrHistory(since);
+    invalidateHistoryCache();
+
+    // Should make a second HTTP request — nock will satisfy it
+    nock('https://sonarr.test')
+      .get('/api/v3/history')
+      .query(true)
+      .reply(200, { records: [] });
+
+    const result = await fetchSonarrHistory(since);
+    expect(result).toEqual([]);
+    expect(nock.isDone()).toBe(true);
+  });
+});

tests/unit/qbittorrent.test.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Tests for server/utils/qbittorrent.js pure utility functions.
  *
@@ -7,6 +8,8 @@
  */
 
 import { mapTorrentToDownload, formatBytes, formatSpeed, formatEta } from '../../server/utils/qbittorrent.js';
+import QBittorrentClient from '../../server/clients/QBittorrentClient.js';
+import nock from 'nock';
 
 // Minimal torrent fixture that satisfies mapTorrentToDownload's expectations
 function makeTorrent(overrides = {}) {
@@ -31,6 +34,35 @@ function makeTorrent(overrides = {}) {
   };
 }
 
+const QBT_URL = 'http://qbittorrent.test:8080';
+
+function makeClient(overrides = {}) {
+  return new QBittorrentClient({
+    id: 'test-qbt',
+    name: 'TestQBT',
+    url: QBT_URL,
+    username: 'admin',
+    password: 'adminadmin',
+    ...overrides
+  });
+}
+
+function mockLogin() {
+  return nock(QBT_URL)
+    .post('/api/v2/auth/login')
+    .reply(200, {}, { 'set-cookie': ['SID=abc123; path=/'] });
+}
+
+function mockSync(rid, response) {
+  return nock(QBT_URL)
+    .get(`/api/v2/sync/maindata?rid=${rid}`)
+    .reply(200, response);
+}
+
+afterEach(() => {
+  nock.cleanAll();
+});
+
 describe('formatBytes', () => {
   it('formats 0 bytes', () => expect(formatBytes(0)).toBe('0 B'));
   it('formats bytes', () => expect(formatBytes(512)).toBe('512 B'));
@@ -109,3 +141,230 @@ describe('mapTorrentToDownload', () => {
     expect(result.savePath).toBe('/dl/');
   });
 });
+
+describe('QBittorrentClient sync API', () => {
+  it('first call uses rid=0 and returns full torrent list', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+
+    mockSync(0, {
+      rid: 1,
+      full_update: true,
+      torrents: {
+        hash01: { name: 'Test1', state: 'downloading', size: 1000, progress: 0.5, dlspeed: 100, eta: 60, num_seeds: 5, num_leechs: 2, availability: 1.0 }
+      }
+    });
+
+    const torrents = await client.getActiveDownloads();
+    expect(torrents).toHaveLength(1);
+    expect(torrents[0].title).toBe('Test1');
+    expect(torrents[0].instanceId).toBe('test-qbt');
+    expect(torrents[0].id).toBe('hash01');
+    expect(client.lastRid).toBe(1);
+  });
+
+  it('subsequent call uses last rid and merges delta', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+
+    // First call
+    mockSync(0, {
+      rid: 1,
+      full_update: true,
+      torrents: {
+        hash01: { name: 'Test1', state: 'downloading', size: 1000, progress: 0.5, dlspeed: 100, eta: 60, num_seeds: 5, num_leechs: 2, availability: 1.0 }
+      }
+    });
+    await client.getActiveDownloads();
+
+    // Second call — delta
+    mockSync(1, {
+      rid: 2,
+      full_update: false,
+      torrents: {
+        hash01: { dlspeed: 200 }
+      }
+    });
+
+    const torrents = await client.getActiveDownloads();
+    expect(torrents).toHaveLength(1);
+    expect(torrents[0].speed).toBe(200);
+    expect(torrents[0].title).toBe('Test1');
+    expect(client.lastRid).toBe(2);
+  });
+
+  it('handles full_update=true on subsequent call', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+
+    // First call
+    mockSync(0, {
+      rid: 1,
+      full_update: true,
+      torrents: {
+        hash01: { name: 'Test1', state: 'downloading', size: 1000, progress: 0.5, dlspeed: 100, eta: 60, num_seeds: 5, num_leechs: 2, availability: 1.0 }
+      }
+    });
+    await client.getActiveDownloads();
+
+    // Server forces full refresh
+    mockSync(1, {
+      rid: 2,
+      full_update: true,
+      torrents: {
+        hash02: { name: 'Test2', state: 'uploading', size: 2000, progress: 1.0, dlspeed: 0, eta: 0, num_seeds: 10, num_leechs: 0, availability: 1.0 }
+      }
+    });
+
+    const torrents = await client.getActiveDownloads();
+    expect(torrents).toHaveLength(1);
+    expect(torrents[0].title).toBe('Test2');
+    expect(torrents[0].id).toBe('hash02');
+    expect(client.lastRid).toBe(2);
+  });
+
+  it('removes torrents when torrents_removed is present', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+
+    mockSync(0, {
+      rid: 1,
+      full_update: true,
+      torrents: {
+        hash01: { name: 'Test1', state: 'downloading', size: 1000, progress: 0.5, dlspeed: 100, eta: 60, num_seeds: 5, num_leechs: 2, availability: 1.0 }
+      }
+    });
+    await client.getActiveDownloads();
+
+    mockSync(1, {
+      rid: 2,
+      full_update: false,
+      torrents_removed: ['hash01']
+    });
+
+    const torrents = await client.getActiveDownloads();
+    expect(torrents).toHaveLength(0);
+  });
+
+  it('falls back to torrents/info when sync fails', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+
+    // Sync fails with 500
+    nock(QBT_URL)
+      .get('/api/v2/sync/maindata?rid=0')
+      .reply(500, { error: 'Internal Server Error' });
+
+    // Legacy succeeds
+    nock(QBT_URL)
+      .get('/api/v2/torrents/info')
+      .reply(200, [
+        { name: 'Fallback', hash: 'fb01', state: 'downloading', size: 1073741824, progress: 0.5, dlspeed: 1048576, eta: 512, num_seeds: 10, num_leechs: 3, availability: 1.0 }
+      ]);
+
+    const torrents = await client.getActiveDownloads();
+    expect(torrents).toHaveLength(1);
+    expect(torrents[0].title).toBe('Fallback');
+    expect(client.fallbackThisCycle).toBe(true);
+  });
+
+  it('uses legacy immediately if already fell back this cycle', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+
+    client.fallbackThisCycle = true;
+
+    // Only legacy should be called
+    nock(QBT_URL)
+      .get('/api/v2/torrents/info')
+      .reply(200, [
+        { name: 'DirectLegacy', hash: 'dl01', state: 'downloading', size: 1000, progress: 0.5, dlspeed: 100, eta: 60, num_seeds: 5, num_leechs: 2, availability: 1.0 }
+      ]);
+
+    // Ensure sync is NOT called
+    const syncScope = nock(QBT_URL)
+      .get('/api/v2/sync/maindata?rid=0')
+      .reply(200, { rid: 1, full_update: true });
+
+    const torrents = await client.getActiveDownloads();
+    expect(torrents).toHaveLength(1);
+    expect(torrents[0].title).toBe('DirectLegacy');
+    expect(syncScope.isDone()).toBe(false);
+  });
+
+  it('re-authenticates on 403 during sync and retries', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+
+    // First sync call returns 403
+    nock(QBT_URL)
+      .get('/api/v2/sync/maindata?rid=0')
+      .reply(403, {});
+
+    // Re-login
+    nock(QBT_URL)
+      .post('/api/v2/auth/login')
+      .reply(200, {}, { 'set-cookie': ['SID=newtoken; path=/'] });
+
+    // Retry succeeds
+    nock(QBT_URL)
+      .get('/api/v2/sync/maindata?rid=0')
+      .reply(200, {
+        rid: 1,
+        full_update: true,
+        torrents: {
+          hash01: { name: 'AfterReauth', state: 'downloading', size: 1000, progress: 0.5, dlspeed: 100, eta: 60, num_seeds: 5, num_leechs: 2, availability: 1.0 }
+        }
+      });
+
+    const torrents = await client.getActiveDownloads();
+    expect(torrents).toHaveLength(1);
+    expect(torrents[0].title).toBe('AfterReauth');
+  });
+
+  it('computes completed from size and progress when missing', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+
+    mockSync(0, {
+      rid: 1,
+      full_update: true,
+      torrents: {
+        hash01: { name: 'NoCompleted', state: 'downloading', size: 1000, progress: 0.5, dlspeed: 100, eta: 60, num_seeds: 5, num_leechs: 2, availability: 1.0 }
+      }
+    });
+
+    const torrents = await client.getActiveDownloads();
+    expect(torrents[0].downloaded).toBe(500);
+  });
+
+  it('resets fallback flag when getAllTorrents resets it', async () => {
+    mockLogin();
+    const client = makeClient();
+    await client.login();
+    client.fallbackThisCycle = true;
+
+    // After reset, sync should be attempted
+    mockSync(0, {
+      rid: 1,
+      full_update: true,
+      torrents: {
+        hash01: { name: 'ResetWorks', state: 'downloading', size: 1000, progress: 0.5, dlspeed: 100, eta: 60, num_seeds: 5, num_leechs: 2, availability: 1.0 }
+      }
+    });
+
+    // Simulate the reset that getAllTorrents performs
+    client.fallbackThisCycle = false;
+    const torrents = await client.getActiveDownloads();
+    expect(torrents[0].title).toBe('ResetWorks');
+    expect(client.fallbackThisCycle).toBe(false);
+  });
+});

tests/unit/requireAuth.test.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Tests for server/middleware/requireAuth.js
  *

tests/unit/sanitizeError.test.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Tests for server/utils/sanitizeError.js
  *

tests/unit/tokenStore.test.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Tests for server/utils/tokenStore.js
  *

tests/unit/verifyCsrf.test.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 /**
  * Tests for server/middleware/verifyCsrf.js
  *

vitest.config.js

@@ -1,3 +1,4 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({