Add extensible notification providers + UI/API

Introduce a provider-based notification system and wire it through the API and admin UI. Added INotificationProvider + notification service implementation and providers (apprise, discord, ntfy, pushover), plus a GET /api/admin/notifications/providers endpoint to expose provider metadata. Refactored code to use provider type strings (removed enum coupling), updated masking/encryption calls, and simplified the test notification endpoint to accept backendId or type+config and call sendToBackend directly.

UI: NotificationsTab now fetches provider metadata and renders provider cards and dynamic config forms (fields driven by provider metadata). Added config field rendering, improved backend cards, and edit/delete actions.

APIs: New providers route, updated admin notification CRUD routes to validate provider types dynamically, updated test route schema. Added download-client categories POST API to fetch categories from clients and wired postImportCategory handling in download-client routes.

Other notable changes: BookDate now fetches Claude models dynamically from Anthropic's Models API; added paginated model fetch helper. Added ALLOW_WEAK_PASSWORD flag exposure to auth providers and password change logic. Doc updates and various tests added/updated. File-organization doc clarifies EPERM fix using stream-based copy.

src/app/api/admin/notifications/[id]/route.ts

@@ -6,7 +6,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
-import { getNotificationService, NotificationBackendType } from '@/lib/services/notification.service';
+import { getNotificationService } from '@/lib/services/notification';
 import { RMABLogger } from '@/lib/utils/logger';
 import { z } from 'zod';
 
@@ -50,7 +50,7 @@ export async function GET(
           success: true,
           backend: {
             ...backend,
-            config: notificationService.maskConfig(backend.type as NotificationBackendType, backend.config),
+            config: notificationService.maskConfig(backend.type, backend.config),
           },
         });
       } catch (error) {
@@ -114,7 +114,7 @@ export async function PUT(
           });
 
           // Encrypt new/changed values
-          finalConfig = notificationService.encryptConfig(existing.type as NotificationBackendType, updatedConfig);
+          finalConfig = notificationService.encryptConfig(existing.type, updatedConfig);
         }
 
         // Update backend
@@ -139,7 +139,7 @@ export async function PUT(
           success: true,
           backend: {
             ...updated,
-            config: notificationService.maskConfig(updated.type as NotificationBackendType, updated.config),
+            config: notificationService.maskConfig(updated.type, updated.config),
           },
         });
       } catch (error) {

src/app/api/admin/notifications/providers/route.ts

@@ -0,0 +1,42 @@
+/**
+ * Component: Notification Providers Metadata API
+ * Documentation: documentation/backend/services/notifications.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { getAllProviderMetadata } from '@/lib/services/notification';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.Admin.Notifications.Providers');
+
+/**
+ * GET /api/admin/notifications/providers
+ * Returns metadata for all registered notification providers
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        const providers = getAllProviderMetadata();
+
+        return NextResponse.json({
+          success: true,
+          providers,
+        });
+      } catch (error) {
+        logger.error('Failed to fetch provider metadata', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+
+        return NextResponse.json(
+          {
+            error: 'FetchError',
+            message: 'Failed to fetch provider metadata',
+          },
+          { status: 500 }
+        );
+      }
+    });
+  });
+}

src/app/api/admin/notifications/route.ts

@@ -6,14 +6,14 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
-import { getNotificationService, NotificationBackendType } from '@/lib/services/notification.service';
+import { getNotificationService, getRegisteredProviderTypes } from '@/lib/services/notification';
 import { RMABLogger } from '@/lib/utils/logger';
 import { z } from 'zod';
 
 const logger = RMABLogger.create('API.Admin.Notifications');
 
 const CreateBackendSchema = z.object({
-  type: z.enum(['discord', 'pushover', 'email', 'slack', 'telegram', 'webhook']),
+  type: z.string().refine((val) => getRegisteredProviderTypes().includes(val), { message: 'Unsupported notification provider type' }),
   name: z.string().min(1),
   config: z.record(z.any()),
   events: z.array(z.enum(['request_pending_approval', 'request_approved', 'request_available', 'request_error'])).min(1),
@@ -37,7 +37,7 @@ export async function GET(request: NextRequest) {
         // Mask sensitive config values
         const maskedBackends = backends.map((backend) => ({
           ...backend,
-          config: notificationService.maskConfig(backend.type as NotificationBackendType, backend.config),
+          config: notificationService.maskConfig(backend.type, backend.config),
         }));
 
         return NextResponse.json({

src/app/api/admin/notifications/test/route.ts

@@ -5,31 +5,17 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
-import { getNotificationService, NotificationBackendType, NotificationPayload } from '@/lib/services/notification.service';
+import { getNotificationService, getRegisteredProviderTypes, NotificationPayload } from '@/lib/services/notification';
 import { RMABLogger } from '@/lib/utils/logger';
 import { z } from 'zod';
 import { prisma } from '@/lib/db';
 
 const logger = RMABLogger.create('API.Admin.Notifications.Test');
 
-const TestNotificationSchema = z.discriminatedUnion('mode', [
-  // Test existing backend by ID (uses stored config)
-  z.object({
-    mode: z.literal('backend'),
-    backendId: z.string(),
-  }),
-  // Test new config before saving
-  z.object({
-    mode: z.literal('config'),
-    type: z.enum(['discord', 'pushover', 'email', 'slack', 'telegram', 'webhook']),
-    config: z.record(z.any()),
-  }),
-]);
-
-// Support legacy format without mode
-const LegacyTestNotificationSchema = z.object({
+// Flexible schema: supports both backendId and type+config formats
+const TestNotificationSchema = z.object({
   backendId: z.string().optional(),
-  type: z.enum(['discord', 'pushover', 'email', 'slack', 'telegram', 'webhook']).optional(),
+  type: z.string().refine((val) => getRegisteredProviderTypes().includes(val), { message: 'Unsupported notification provider type' }).optional(),
   config: z.record(z.any()).optional(),
 });
 
@@ -42,66 +28,37 @@ export async function POST(request: NextRequest) {
     return requireAdmin(req, async () => {
       try {
         const body = await request.json();
+        const parsed = TestNotificationSchema.parse(body);
 
-        // Support legacy format for backward compatibility
-        const legacyParsed = LegacyTestNotificationSchema.safeParse(body);
-
-        let type: NotificationBackendType;
+        let type: string;
         let encryptedConfig: any;
 
         const notificationService = getNotificationService();
 
-        if (legacyParsed.success) {
-          // Legacy format
-          if (legacyParsed.data.backendId) {
-            // Test existing backend
-            const backend = await prisma.notificationBackend.findUnique({
-              where: { id: legacyParsed.data.backendId },
-            });
+        if (parsed.backendId) {
+          // Test existing backend by ID (uses stored config)
+          const backend = await prisma.notificationBackend.findUnique({
+            where: { id: parsed.backendId },
+          });
 
-            if (!backend) {
-              return NextResponse.json(
-                { error: 'NotFound', message: 'Backend not found' },
-                { status: 404 }
-              );
-            }
-
-            type = backend.type as NotificationBackendType;
-            encryptedConfig = backend.config; // Already encrypted in DB
-          } else if (legacyParsed.data.type && legacyParsed.data.config) {
-            // Test new config
-            type = legacyParsed.data.type as NotificationBackendType;
-            encryptedConfig = notificationService.encryptConfig(type, legacyParsed.data.config);
-          } else {
+          if (!backend) {
             return NextResponse.json(
-              { error: 'ValidationError', message: 'Must provide either backendId or type+config' },
-              { status: 400 }
+              { error: 'NotFound', message: 'Backend not found' },
+              { status: 404 }
             );
           }
+
+          type = backend.type;
+          encryptedConfig = backend.config; // Already encrypted in DB
+        } else if (parsed.type && parsed.config) {
+          // Test new config before saving
+          type = parsed.type;
+          encryptedConfig = notificationService.encryptConfig(type, parsed.config);
         } else {
-          // New format with discriminated union
-          const parsed = TestNotificationSchema.parse(body);
-
-          if (parsed.mode === 'backend') {
-            // Test existing backend
-            const backend = await prisma.notificationBackend.findUnique({
-              where: { id: parsed.backendId },
-            });
-
-            if (!backend) {
-              return NextResponse.json(
-                { error: 'NotFound', message: 'Backend not found' },
-                { status: 404 }
-              );
-            }
-
-            type = backend.type as NotificationBackendType;
-            encryptedConfig = backend.config; // Already encrypted in DB
-          } else {
-            // Test new config
-            type = parsed.type;
-            encryptedConfig = notificationService.encryptConfig(type, parsed.config);
-          }
+          return NextResponse.json(
+            { error: 'ValidationError', message: 'Must provide either backendId or type+config' },
+            { status: 400 }
+          );
         }
 
         // Create test payload
@@ -117,7 +74,7 @@ export async function POST(request: NextRequest) {
         // Send test notification synchronously (not via job queue)
         try {
           // Call sendToBackend directly
-          await (notificationService as any).sendToBackend(type, encryptedConfig, testPayload);
+          await notificationService.sendToBackend(type, encryptedConfig, testPayload);
 
           logger.info(`Test notification sent successfully for ${type}`, {
             adminId: req.user?.sub,

src/app/api/admin/settings/download-clients/[id]/route.ts

@@ -38,6 +38,7 @@ export async function PUT(
           localPath,
           category,
           customPath,
+          postImportCategory,
         } = body;
 
         const config = await getConfigService();
@@ -76,6 +77,7 @@ export async function PUT(
           localPath: localPath !== undefined ? localPath : existingClient.localPath,
           category: category !== undefined ? category : existingClient.category,
           customPath: customPath !== undefined ? (customPath || undefined) : existingClient.customPath,
+          postImportCategory: postImportCategory !== undefined ? (postImportCategory || undefined) : existingClient.postImportCategory,
         };
 
         // Validate path mapping if enabled

src/app/api/admin/settings/download-clients/categories/route.ts

@@ -0,0 +1,104 @@
+/**
+ * Component: Fetch Download Client Categories API
+ * Documentation: documentation/phase3/download-clients.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { getConfigService } from '@/lib/services/config.service';
+import { getDownloadClientManager, DownloadClientConfig } from '@/lib/services/download-client-manager.service';
+import { SUPPORTED_CLIENT_TYPES } from '@/lib/interfaces/download-client.interface';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.Admin.Settings.DownloadClients.Categories');
+
+/**
+ * POST - Fetch categories from a download client
+ * Accepts same connection config as the test endpoint
+ */
+export async function POST(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        const body = await request.json();
+        const {
+          clientId,
+          type,
+          name: clientName,
+          url,
+          username,
+          password,
+          disableSSLVerify,
+          remotePathMappingEnabled,
+          remotePath,
+          localPath,
+        } = body;
+
+        if (!SUPPORTED_CLIENT_TYPES.includes(type)) {
+          return NextResponse.json(
+            { error: `Invalid client type. Must be one of: ${SUPPORTED_CLIENT_TYPES.join(', ')}` },
+            { status: 400 }
+          );
+        }
+
+        if (!url) {
+          return NextResponse.json(
+            { error: 'URL is required' },
+            { status: 400 }
+          );
+        }
+
+        const config = await getConfigService();
+        const manager = getDownloadClientManager(config);
+
+        // If editing and password not provided, use stored password
+        let effectivePassword = password;
+        let effectiveUsername = username;
+
+        if (clientId && !password) {
+          const existingClients = await manager.getAllClients();
+          const existingClient = existingClients.find(c => c.id === clientId);
+
+          if (!existingClient) {
+            return NextResponse.json(
+              { error: 'Client not found' },
+              { status: 404 }
+            );
+          }
+
+          effectivePassword = existingClient.password;
+          if (!username && existingClient.username) {
+            effectiveUsername = existingClient.username;
+          }
+        }
+
+        const testConfig: DownloadClientConfig = {
+          id: 'categories-fetch',
+          type,
+          name: clientName || type,
+          enabled: true,
+          url,
+          username: effectiveUsername || '',
+          password: effectivePassword || '',
+          disableSSLVerify: disableSSLVerify || false,
+          remotePathMappingEnabled: remotePathMappingEnabled || false,
+          remotePath: remotePath || undefined,
+          localPath: localPath || undefined,
+          category: 'readmeabook',
+        };
+
+        const service = await manager.createClientFromConfig(testConfig);
+        const categories = await service.getCategories();
+
+        return NextResponse.json({ success: true, categories });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error('Failed to fetch categories', { error: message });
+        return NextResponse.json(
+          { success: false, error: message },
+          { status: 400 }
+        );
+      }
+    });
+  });
+}

src/app/api/admin/settings/download-clients/route.ts

@@ -63,6 +63,7 @@ export async function POST(request: NextRequest) {
           localPath,
           category,
           customPath,
+          postImportCategory,
         } = body;
 
         // Validate type
@@ -138,6 +139,7 @@ export async function POST(request: NextRequest) {
           localPath: localPath || undefined,
           category: category || 'readmeabook',
           customPath: customPath || undefined,
+          postImportCategory: postImportCategory || undefined,
         };
 
         // Test connection before saving

src/app/api/audiobooks/search-torrents/route.ts

@@ -86,7 +86,6 @@ export async function POST(request: NextRequest) {
 
       // Search Prowlarr for each group and combine results
       const prowlarr = await getProwlarrService();
-      const searchQuery = title; // Title only - cast wide net
       const allResults = [];
 
       for (let i = 0; i < groups.length; i++) {
@@ -94,7 +93,7 @@ export async function POST(request: NextRequest) {
         logger.debug(`Searching group ${i + 1}/${groups.length}: ${getGroupDescription(group)}`);
 
         try {
-          const groupResults = await prowlarr.search(searchQuery, {
+          const groupResults = await prowlarr.searchWithVariations(title, author, {
             categories: group.categories,
             indexerIds: group.indexerIds,
             maxResults: 100, // Limit per group

src/app/api/auth/change-password/route.ts

@@ -39,7 +39,8 @@ export async function POST(request: NextRequest) {
       }
 
       // Validate new password length
-      if (newPassword.length < 8) {
+      const allowWeakPassword = process.env.ALLOW_WEAK_PASSWORD === 'true';
+      if (!allowWeakPassword && newPassword.length < 8) {
         return NextResponse.json(
           {
             success: false,

src/app/api/auth/providers/route.ts

@@ -18,6 +18,9 @@ export async function GET() {
     // Check if local login is disabled via environment variable
     const localLoginDisabled = process.env.DISABLE_LOCAL_LOGIN === 'true';
 
+    // Check if weak passwords are allowed via environment variable
+    const allowWeakPassword = process.env.ALLOW_WEAK_PASSWORD === 'true';
+
     // Check if automation (Phase 3) is configured by checking for Prowlarr/indexer config
     const indexerType = await configService.get('indexer.type');
     const prowlarrUrl = await configService.get('indexer.prowlarr_url');
@@ -47,6 +50,7 @@ export async function GET() {
         hasLocalUsers,
         oidcProviderName: oidcEnabled ? oidcProviderName : null,
         localLoginDisabled,
+        allowWeakPassword,
         automationEnabled,
       });
     } else {
@@ -65,6 +69,7 @@ export async function GET() {
         hasLocalUsers,
         oidcProviderName: null,
         localLoginDisabled,
+        allowWeakPassword,
         automationEnabled,
       });
     }
@@ -72,6 +77,7 @@ export async function GET() {
     logger.error('Failed to fetch auth providers', { error: error instanceof Error ? error.message : String(error) });
     // Default to Plex mode if config can't be read
     const localLoginDisabled = process.env.DISABLE_LOCAL_LOGIN === 'true';
+    const allowWeakPassword = process.env.ALLOW_WEAK_PASSWORD === 'true';
     return NextResponse.json({
       backendMode: 'plex',
       providers: ['plex'],
@@ -79,6 +85,7 @@ export async function GET() {
       hasLocalUsers: false,
       oidcProviderName: null,
       localLoginDisabled,
+      allowWeakPassword,
       automationEnabled: false,
     });
   }

src/app/api/bookdate/test-connection/route.ts

@@ -9,6 +9,49 @@ import { RMABLogger } from '@/lib/utils/logger';
 
 const logger = RMABLogger.create('API.BookDate.TestConnection');
 
+// Fetch available Claude models from the Anthropic API
+async function fetchClaudeModels(apiKey: string): Promise<{ id: string; name: string }[]> {
+  const allModels: { id: string; name: string }[] = [];
+  let afterId: string | undefined;
+
+  // Paginate through all available models
+  do {
+    const params = new URLSearchParams({ limit: '1000' });
+    if (afterId) {
+      params.set('after_id', afterId);
+    }
+
+    const response = await fetch(
+      `https://api.anthropic.com/v1/models?${params.toString()}`,
+      {
+        headers: {
+          'x-api-key': apiKey,
+          'anthropic-version': '2023-06-01',
+        },
+      }
+    );
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error('Claude API error', { error: errorText });
+      throw new Error('Invalid Claude API key or connection failed');
+    }
+
+    const data = await response.json();
+
+    for (const model of data.data) {
+      allModels.push({
+        id: model.id,
+        name: model.display_name || model.id,
+      });
+    }
+
+    afterId = data.has_more ? data.last_id : undefined;
+  } while (afterId);
+
+  return allModels;
+}
+
 // Helper functions for custom provider
 function isValidBaseUrl(url: string): boolean {
   try {
@@ -141,32 +184,10 @@ async function authenticatedHandler(req: AuthenticatedRequest) {
         .sort((a: any, b: any) => a.name.localeCompare(b.name));
 
     } else if (provider === 'claude') {
-      // Claude: Hardcoded list (Anthropic doesn't have a public models API endpoint)
-      models = [
-        { id: 'claude-sonnet-4-5-20250929', name: 'Claude Sonnet 4.5 (Latest)' },
-        { id: 'claude-3-7-sonnet-20250219', name: 'Claude 3.7 Sonnet' },
-        { id: 'claude-opus-4-20250514', name: 'Claude Opus 4' },
-        { id: 'claude-3-5-haiku-20241022', name: 'Claude 3.5 Haiku' },
-      ];
-
-      // Test connection with a simple API call
-      const response = await fetch('https://api.anthropic.com/v1/messages', {
-        method: 'POST',
-        headers: {
-          'x-api-key': testApiKey,
-          'anthropic-version': '2023-06-01',
-          'content-type': 'application/json',
-        },
-        body: JSON.stringify({
-          model: 'claude-3-5-haiku-20241022',
-          max_tokens: 10,
-          messages: [{ role: 'user', content: 'Test' }],
-        }),
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        logger.error('Claude API error', { error: errorText });
+      // Claude: Fetch models dynamically from the Anthropic Models API
+      try {
+        models = await fetchClaudeModels(testApiKey);
+      } catch {
         return NextResponse.json(
           { error: 'Invalid Claude API key or connection failed' },
           { status: 400 }
@@ -333,32 +354,10 @@ async function unauthenticatedHandler(req: NextRequest) {
         .sort((a: any, b: any) => a.name.localeCompare(b.name));
 
     } else if (provider === 'claude') {
-      // Claude: Hardcoded list (Anthropic doesn't have a public models API endpoint)
-      models = [
-        { id: 'claude-sonnet-4-5-20250929', name: 'Claude Sonnet 4.5 (Latest)' },
-        { id: 'claude-3-7-sonnet-20250219', name: 'Claude 3.7 Sonnet' },
-        { id: 'claude-opus-4-20250514', name: 'Claude Opus 4' },
-        { id: 'claude-3-5-haiku-20241022', name: 'Claude 3.5 Haiku' },
-      ];
-
-      // Test connection with a simple API call
-      const response = await fetch('https://api.anthropic.com/v1/messages', {
-        method: 'POST',
-        headers: {
-          'x-api-key': apiKey,
-          'anthropic-version': '2023-06-01',
-          'content-type': 'application/json',
-        },
-        body: JSON.stringify({
-          model: 'claude-3-5-haiku-20241022',
-          max_tokens: 10,
-          messages: [{ role: 'user', content: 'Test' }],
-        }),
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        logger.error('Claude API error', { error: errorText });
+      // Claude: Fetch models dynamically from the Anthropic Models API
+      try {
+        models = await fetchClaudeModels(apiKey);
+      } catch {
         return NextResponse.json(
           { error: 'Invalid Claude API key or connection failed' },
           { status: 400 }

src/app/api/requests/[id]/interactive-search/route.ts

@@ -8,6 +8,7 @@ import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
 import { getProwlarrService } from '@/lib/integrations/prowlarr.service';
 import { rankTorrents } from '@/lib/utils/ranking-algorithm';
+import { groupIndexersByCategories, getGroupDescription } from '@/lib/utils/indexer-grouping';
 import { RMABLogger } from '@/lib/utils/logger';
 import { resolveInteractiveSearchAccess } from '@/lib/utils/permissions';
 
@@ -97,9 +98,8 @@ export async function POST(
       }
 
       const indexersConfig = JSON.parse(indexersConfigStr);
-      const enabledIndexerIds = indexersConfig.map((indexer: any) => indexer.id);
 
-      if (enabledIndexerIds.length === 0) {
+      if (indexersConfig.length === 0) {
         return NextResponse.json(
           { error: 'ConfigError', message: 'No indexers enabled. Please enable at least one indexer in settings.' },
           { status: 400 }
@@ -115,22 +115,53 @@ export async function POST(
       const flagConfigStr = await configService.get('indexer_flag_config');
       const flagConfigs = flagConfigStr ? JSON.parse(flagConfigStr) : [];
 
-      // Search Prowlarr for torrents - ONLY enabled indexers
-      const prowlarr = await getProwlarrService();
-      // Use custom title if provided, otherwise use audiobook's title
-      const searchQuery = customTitle || requestRecord.audiobook.title;
+      // Group indexers by their category configuration
+      const { groups, skippedIndexers } = groupIndexersByCategories(indexersConfig);
 
-      logger.info(`Searching ${enabledIndexerIds.length} enabled indexers`, { searchQuery });
+      if (skippedIndexers.length > 0) {
+        const skippedNames = skippedIndexers.map(idx => idx.name).join(', ');
+        logger.info(`Skipping ${skippedIndexers.length} indexer(s) with no audiobook categories: ${skippedNames}`);
+      }
+
+      // Use custom title if provided, otherwise use audiobook's title
+      const searchTitle = customTitle || requestRecord.audiobook.title;
+      const searchAuthor = requestRecord.audiobook.author;
+
+      logger.info(`Searching ${indexersConfig.length - skippedIndexers.length} enabled indexers in ${groups.length} group${groups.length > 1 ? 's' : ''}`, { searchTitle });
       if (customTitle) {
         logger.debug('Using custom search title', { customTitle, originalTitle: requestRecord.audiobook.title });
       }
 
-      const results = await prowlarr.search(searchQuery, {
-        indexerIds: enabledIndexerIds,
-        maxResults: 100, // Increased limit for broader search
+      // Log each group for transparency
+      groups.forEach((group, index) => {
+        logger.debug(`Group ${index + 1}: ${getGroupDescription(group)}`);
       });
 
-      logger.debug(`Found ${results.length} raw results`, { requestId: id });
+      // Search Prowlarr for each group and combine results
+      const prowlarr = await getProwlarrService();
+      const allResults = [];
+
+      for (let i = 0; i < groups.length; i++) {
+        const group = groups[i];
+        logger.debug(`Searching group ${i + 1}/${groups.length}: ${getGroupDescription(group)}`);
+
+        try {
+          const groupResults = await prowlarr.searchWithVariations(searchTitle, searchAuthor, {
+            categories: group.categories,
+            indexerIds: group.indexerIds,
+            maxResults: 100,
+          });
+
+          logger.debug(`Group ${i + 1} returned ${groupResults.length} results`);
+          allResults.push(...groupResults);
+        } catch (error) {
+          logger.error(`Group ${i + 1} search failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+          // Continue with other groups even if one fails
+        }
+      }
+
+      const results = allResults;
+      logger.info(`Found ${results.length} total results from ${groups.length} group${groups.length > 1 ? 's' : ''}`, { requestId: id });
 
       if (results.length === 0) {
         return NextResponse.json({
@@ -140,12 +171,31 @@ export async function POST(
         });
       }
 
+      // Fetch runtime from Audnexus if ASIN available (for size-based scoring)
+      let durationMinutes: number | undefined;
+      if (requestRecord.audiobook.audibleAsin) {
+        try {
+          const { getAudibleService } = await import('@/lib/integrations/audible.service');
+          const audibleService = getAudibleService();
+          const runtime = await audibleService.getRuntime(requestRecord.audiobook.audibleAsin);
+          if (runtime) {
+            durationMinutes = runtime;
+            logger.info(`Fetched runtime: ${runtime} minutes for ASIN ${requestRecord.audiobook.audibleAsin}`);
+          } else {
+            logger.debug(`No runtime found for ASIN ${requestRecord.audiobook.audibleAsin}`);
+          }
+        } catch (error) {
+          logger.debug(`Failed to fetch runtime for ASIN ${requestRecord.audiobook.audibleAsin}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+      }
+
       // Rank torrents using the ranking algorithm with indexer priorities and flag configs
       // Always use the audiobook's title/author for ranking (not custom search query)
       // requireAuthor: false - interactive mode, show all results for user decision
       const rankedResults = rankTorrents(results, {
         title: requestRecord.audiobook.title,
         author: requestRecord.audiobook.author,
+        durationMinutes,
       }, {
         indexerPriorities,
         flagConfigs,
@@ -160,17 +210,23 @@ export async function POST(
       const top3 = rankedResults.slice(0, 3);
       if (top3.length > 0) {
         logger.debug('==================== RANKING DEBUG ====================');
-        logger.debug('Search parameters', { searchQuery, requestedTitle: requestRecord.audiobook.title, requestedAuthor: requestRecord.audiobook.author });
+        logger.debug('Search parameters', { searchTitle, requestedTitle: requestRecord.audiobook.title, requestedAuthor: requestRecord.audiobook.author });
         logger.debug(`Top ${top3.length} results (out of ${rankedResults.length} total)`);
         logger.debug('--------------------------------------------------------');
         top3.forEach((result, index) => {
+          const sizeMB = (result.size / (1024 * 1024)).toFixed(1);
+          const mbPerMin = durationMinutes ? ((result.size / (1024 * 1024)) / durationMinutes).toFixed(2) : 'N/A';
+
           logger.debug(`${index + 1}. "${result.title}"`, {
             indexer: result.indexer,
             indexerId: result.indexerId,
             baseScore: `${result.score.toFixed(1)}/100`,
             matchScore: `${result.breakdown.matchScore.toFixed(1)}/60`,
-            formatScore: `${result.breakdown.formatScore.toFixed(1)}/25 (${result.format || 'unknown'})`,
-            seederScore: `${result.breakdown.seederScore.toFixed(1)}/15 (${result.seeders} seeders)`,
+            formatScore: `${result.breakdown.formatScore.toFixed(1)}/10 (${result.format || 'unknown'})`,
+            sizeScore: durationMinutes
+              ? `${result.breakdown.sizeScore.toFixed(1)}/15 (${sizeMB} MB, ${mbPerMin} MB/min)`
+              : 'N/A (no runtime)',
+            seederScore: `${result.breakdown.seederScore.toFixed(1)}/15 (${result.seeders !== undefined ? result.seeders + ' seeders' : 'N/A for Usenet'})`,
             bonusPoints: `+${result.bonusPoints.toFixed(1)}`,
             bonusModifiers: result.bonusModifiers.map(mod => `${mod.reason}: +${mod.points.toFixed(1)}`),
             finalScore: result.finalScore.toFixed(1),

src/app/api/setup/download-client-categories/route.ts

@@ -0,0 +1,63 @@
+/**
+ * Component: Setup Wizard Download Client Categories API
+ * Documentation: documentation/setup-wizard.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getConfigService } from '@/lib/services/config.service';
+import { getDownloadClientManager, DownloadClientConfig } from '@/lib/services/download-client-manager.service';
+import { SUPPORTED_CLIENT_TYPES } from '@/lib/interfaces/download-client.interface';
+import { requireSetupIncomplete } from '@/lib/middleware/auth';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.Setup.DownloadClientCategories');
+
+/**
+ * POST - Fetch categories from a download client during setup wizard
+ */
+export async function POST(request: NextRequest) {
+  return requireSetupIncomplete(request, async (req) => {
+    try {
+      const { type, name, url, username, password, disableSSLVerify } = await req.json();
+
+      if (!type || !url) {
+        return NextResponse.json(
+          { success: false, error: 'Type and URL are required' },
+          { status: 400 }
+        );
+      }
+
+      if (!SUPPORTED_CLIENT_TYPES.includes(type)) {
+        return NextResponse.json(
+          { success: false, error: `Invalid client type. Must be one of: ${SUPPORTED_CLIENT_TYPES.join(', ')}` },
+          { status: 400 }
+        );
+      }
+
+      const testConfig: DownloadClientConfig = {
+        id: 'setup-categories',
+        type,
+        name: name || type,
+        enabled: true,
+        url,
+        username: username || '',
+        password: password || '',
+        disableSSLVerify: disableSSLVerify || false,
+        remotePathMappingEnabled: false,
+      };
+
+      const configService = getConfigService();
+      const manager = getDownloadClientManager(configService);
+      const service = await manager.createClientFromConfig(testConfig);
+      const categories = await service.getCategories();
+
+      return NextResponse.json({ success: true, categories });
+    } catch (error) {
+      logger.error('Failed to fetch categories', { error: error instanceof Error ? error.message : String(error) });
+      return NextResponse.json(
+        { success: false, error: error instanceof Error ? error.message : 'Failed to fetch categories' },
+        { status: 500 }
+      );
+    }
+  });
+}