Add request approval system and audiobook path template

Implements admin approval workflow for user requests with global and per-user auto-approve controls. Adds new request statuses ('awaiting_approval', 'denied'), related API endpoints, and UI for pending approvals. Introduces configurable audiobook organization path template with validation and preview in settings, updates database schema and migrations for new fields.

src/lib/processors/organize-files.processor.ts

@@ -44,10 +44,47 @@ export async function processOrganizeFiles(payload: OrganizeFilesPayload): Promi
 
     logger.info(`Organizing: ${audiobook.title} by ${audiobook.author}`);
 
+    // Fetch year from multiple sources (priority order)
+    let year = audiobook.year || undefined;
+    logger.info(`Initial year from audiobook record: ${year || 'null'}`);
+
+    if (!year && audiobook.audibleAsin) {
+      logger.info(`No year in audiobook record, attempting to fetch from AudibleCache for ASIN: ${audiobook.audibleAsin}`);
+
+      // Try AudibleCache (for popular/new releases)
+      const audibleCache = await prisma.audibleCache.findUnique({
+        where: { asin: audiobook.audibleAsin },
+        select: { releaseDate: true },
+      });
+
+      if (audibleCache?.releaseDate) {
+        logger.info(`Found AudibleCache entry with releaseDate: ${audibleCache.releaseDate}`);
+        year = new Date(audibleCache.releaseDate).getFullYear();
+        logger.info(`Extracted year ${year} from AudibleCache releaseDate`);
+
+        // Update audiobook record with year for future use
+        await prisma.audiobook.update({
+          where: { id: audiobookId },
+          data: { year },
+        });
+        logger.info(`Updated audiobook record with year ${year}`);
+      } else {
+        logger.info(`No year found in AudibleCache for ASIN ${audiobook.audibleAsin}`);
+      }
+    }
+
+    logger.info(`Final year value for path organization: ${year || 'null (year will be omitted from path)'}`)
+
     // Get file organizer (reads media_dir from database config)
     const organizer = await getFileOrganizer();
 
-    // Organize files (pass logger to file organizer)
+    // Read path template from configuration
+    const templateConfig = await prisma.configuration.findUnique({
+      where: { key: 'audiobook_path_template' },
+    });
+    const template = templateConfig?.value || '{author}/{title} {asin}';
+
+    // Organize files (pass template and logger to file organizer)
     const result = await organizer.organize(
       downloadPath,
       {
@@ -56,7 +93,9 @@ export async function processOrganizeFiles(payload: OrganizeFilesPayload): Promi
         narrator: audiobook.narrator || undefined,
         coverArtUrl: audiobook.coverArtUrl || undefined,
         asin: audiobook.audibleAsin || undefined,
+        year,
       },
+      template,
       jobId ? { jobId, context: 'FileOrganizer' } : undefined
     );
 

src/lib/services/audiobookshelf/api.ts

@@ -152,3 +152,34 @@ export async function triggerABSItemMatch(itemId: string, asin?: string) {
     logger.error(`Failed to trigger match for item ${itemId}`, { error: error instanceof Error ? error.message : String(error) });
   }
 }
+
+/**
+ * Delete a library item from Audiobookshelf
+ * Note: This only removes the item from Audiobookshelf's database, not the actual files
+ *
+ * @param itemId - The Audiobookshelf item ID to delete
+ */
+export async function deleteABSItem(itemId: string): Promise<void> {
+  const configService = getConfigService();
+  const serverUrl = await configService.get('audiobookshelf.server_url');
+  const apiToken = await configService.get('audiobookshelf.api_token');
+
+  if (!serverUrl || !apiToken) {
+    throw new Error('Audiobookshelf not configured');
+  }
+
+  const url = `${serverUrl.replace(/\/$/, '')}/api/items/${itemId}`;
+
+  const response = await fetch(url, {
+    method: 'DELETE',
+    headers: {
+      'Authorization': `Bearer ${apiToken}`,
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`ABS API error: ${response.status} ${response.statusText}`);
+  }
+
+  logger.info(`Deleted library item ${itemId} from Audiobookshelf`);
+}

src/lib/services/request-delete.service.ts

@@ -9,6 +9,7 @@ import { prisma } from '../db';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { RMABLogger } from '../utils/logger';
+import { buildAudiobookPath } from '../utils/file-organizer';
 
 const logger = RMABLogger.create('RequestDelete');
 
@@ -52,6 +53,7 @@ export async function deleteRequest(
             id: true,
             title: true,
             author: true,
+            narrator: true,
             audibleAsin: true,
             plexGuid: true,
             absItemId: true,
@@ -190,42 +192,34 @@ export async function deleteRequest(
       const { getConfigService } = await import('./config.service');
       const configService = getConfigService();
       const mediaDir = (await configService.get('media_dir')) || '/media/audiobooks';
+      const template = (await configService.get('audiobook_path_template')) || '{author}/{title} {asin}';
 
-      // Sanitize author and title for path (same logic as file-organizer.ts)
-      const sanitizedAuthor = sanitizePath(request.audiobook.author);
-      const sanitizedTitle = sanitizePath(request.audiobook.title);
-
-      // Build folder name with optional year and ASIN (matches file-organizer.ts logic)
-      let folderName = sanitizedTitle;
-
-      // Get ASIN and check for year in AudibleCache
-      const asin = request.audiobook.audibleAsin;
+      // Fetch year from audible cache if ASIN is available
       let year: number | undefined;
-
-      if (asin) {
-        // Try to get year from AudibleCache if it exists
+      if (request.audiobook.audibleAsin) {
         const audibleCache = await prisma.audibleCache.findUnique({
-          where: { asin },
+          where: { asin: request.audiobook.audibleAsin },
           select: { releaseDate: true },
         });
-
         if (audibleCache?.releaseDate) {
           year = new Date(audibleCache.releaseDate).getFullYear();
         }
       }
 
-      if (year) {
-        folderName = `${folderName} (${year})`;
-      }
+      // Build path using centralized function
+      const titleFolderPath = buildAudiobookPath(
+        mediaDir,
+        template,
+        {
+          author: request.audiobook.author,
+          title: request.audiobook.title,
+          narrator: request.audiobook.narrator || undefined,
+          asin: request.audiobook.audibleAsin || undefined,
+          year,
+        }
+      );
 
-      if (asin) {
-        folderName = `${folderName} ${asin}`;
-      }
-
-      // Build path: [media_dir]/[author]/[title (year) asin]/
-      const titleFolderPath = path.join(mediaDir, sanitizedAuthor, folderName);
-
-      // Check if folder exists
+      // Check if folder exists and delete it
       try {
         await fs.access(titleFolderPath);
 
@@ -235,20 +229,9 @@ export async function deleteRequest(
         logger.info(`Deleted media directory: ${titleFolderPath}`);
         filesDeleted = true;
       } catch (accessError) {
-        // Folder doesn't exist - try without year/ASIN (fallback for older files)
-        const fallbackPath = path.join(mediaDir, sanitizedAuthor, sanitizedTitle);
-        try {
-          await fs.access(fallbackPath);
-          await fs.rm(fallbackPath, { recursive: true, force: true });
-          logger.info(`Deleted media directory (fallback path): ${fallbackPath}`);
-          filesDeleted = true;
-        } catch (fallbackError) {
-          // Neither path exists - that's okay
-          logger.info(
-            `Media directory not found (tried: ${titleFolderPath}, ${fallbackPath})`
-          );
-          filesDeleted = false;
-        }
+        // Folder doesn't exist - that's okay
+        logger.info(`Media directory not found: ${titleFolderPath}`);
+        filesDeleted = false;
       }
     } catch (error) {
       logger.error(
@@ -265,6 +248,23 @@ export async function deleteRequest(
       const configService = getConfigService();
       const backendMode = await configService.getBackendMode();
 
+      // If backend is Audiobookshelf, delete the library item from ABS
+      if (backendMode === 'audiobookshelf' && request.audiobook.absItemId) {
+        try {
+          const { deleteABSItem } = await import('../services/audiobookshelf/api');
+          await deleteABSItem(request.audiobook.absItemId);
+          logger.info(
+            `Deleted Audiobookshelf library item ${request.audiobook.absItemId} for "${request.audiobook.title}"`
+          );
+        } catch (absError) {
+          logger.error(
+            `Error deleting Audiobookshelf library item ${request.audiobook.absItemId}`,
+            { error: absError instanceof Error ? absError.message : String(absError) }
+          );
+          // Continue with deletion even if ABS deletion fails
+        }
+      }
+
       // Delete ALL plex_library records matching this audiobook's title and author
       // This handles cases where there might be duplicate library records
       // and ensures the book doesn't show as "In Your Library" during searches
@@ -377,21 +377,3 @@ export async function deleteRequest(
     };
   }
 }
-
-/**
- * Sanitize a path component (removes invalid characters)
- */
-function sanitizePath(input: string): string {
-  return (
-    input
-      // Remove invalid path characters
-      .replace(/[<>:"/\\|?*]/g, '')
-      // Trim dots and spaces from start/end
-      .replace(/^[.\s]+|[.\s]+$/g, '')
-      // Collapse multiple spaces
-      .replace(/\s+/g, ' ')
-      // Limit length
-      .substring(0, 200)
-      .trim()
-  );
-}

src/lib/utils/PATH_TEMPLATE_README.md

@@ -0,0 +1,231 @@
+# Path Template Engine Utility
+
+Location: `src/lib/utils/path-template.util.ts`
+
+## Overview
+
+Provides template variable substitution, validation, and preview generation for audiobook file organization paths.
+
+## Features
+
+1. **Template Variable Substitution** - Replace variables with actual values
+2. **Template Validation** - Validate template syntax and characters
+3. **Mock Preview Generation** - Generate example paths with sample data
+4. **Path Sanitization** - Automatic removal of invalid file path characters
+
+## Supported Variables
+
+- `{author}` - Audiobook author name
+- `{title}` - Audiobook title
+- `{narrator}` - Audiobook narrator (optional)
+- `{asin}` - Amazon ASIN identifier (optional)
+
+## API Reference
+
+### `substituteTemplate(template: string, variables: TemplateVariables): string`
+
+Substitute template variables with actual values.
+
+**Features:**
+- Handles missing/null variables gracefully (omits them)
+- Applies path sanitization to all substituted values
+- Removes multiple consecutive spaces
+- Normalizes path separators (converts backslashes to forward slashes)
+
+**Example:**
+```typescript
+const result = substituteTemplate(
+  '{author}/{title}',
+  { author: 'Brandon Sanderson', title: 'Mistborn' }
+);
+// Returns: "Brandon Sanderson/Mistborn"
+```
+
+### `validateTemplate(template: string): ValidationResult`
+
+Validate a path template string.
+
+**Checks for:**
+- Valid variable names only (rejects unknown variables)
+- No invalid file path characters outside of variables (`:`, `|`, `<`, `>`, `*`, `?`, `"`)
+- Non-empty template
+- Relative paths only (no absolute paths)
+
+**Returns:**
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  error?: string; // Helpful error message if invalid
+}
+```
+
+**Example:**
+```typescript
+const result = validateTemplate('{author}/{title}');
+// Returns: { valid: true }
+
+const invalid = validateTemplate('{invalid}/{title}');
+// Returns: { valid: false, error: "Unknown variable: {invalid}. Valid variables are: {author}, {title}, {narrator}, {asin}" }
+```
+
+### `generateMockPreviews(template: string): string[]`
+
+Generate 2-3 example paths using mock audiobook data.
+
+**Mock Examples:**
+1. Brandon Sanderson / Mistborn: The Final Empire / Michael Kramer / B002UZMLXM
+2. Douglas Adams / The Hitchhiker's Guide to the Galaxy / Stephen Fry / B0009JKV9W
+3. Andy Weir / Project Hail Mary / (no narrator) / B08G9PRS1K
+
+**Example:**
+```typescript
+const previews = generateMockPreviews('{author}/{title}');
+// Returns:
+// [
+//   "Brandon Sanderson/Mistborn The Final Empire",
+//   "Douglas Adams/The Hitchhiker's Guide to the Galaxy",
+//   "Andy Weir/Project Hail Mary"
+// ]
+```
+
+### `getValidVariables(): string[]`
+
+Get list of valid template variable names.
+
+**Example:**
+```typescript
+const variables = getValidVariables();
+// Returns: ['author', 'title', 'narrator', 'asin']
+```
+
+## Usage Examples
+
+### Basic Template
+```typescript
+import { substituteTemplate } from '@/lib/utils/path-template.util';
+
+const result = substituteTemplate(
+  '{author}/{title}',
+  {
+    author: 'Brandon Sanderson',
+    title: 'Mistborn: The Final Empire'
+  }
+);
+// Result: "Brandon Sanderson/Mistborn The Final Empire"
+```
+
+### Template with Optional Variables
+```typescript
+// With narrator
+const withNarrator = substituteTemplate(
+  '{author}/{title}/{narrator}',
+  {
+    author: 'Douglas Adams',
+    title: "The Hitchhiker's Guide to the Galaxy",
+    narrator: 'Stephen Fry'
+  }
+);
+// Result: "Douglas Adams/The Hitchhiker's Guide to the Galaxy/Stephen Fry"
+
+// Without narrator (gracefully omitted)
+const withoutNarrator = substituteTemplate(
+  '{author}/{title}/{narrator}',
+  {
+    author: 'Andy Weir',
+    title: 'Project Hail Mary'
+    // No narrator
+  }
+);
+// Result: "Andy Weir/Project Hail Mary"
+```
+
+### Template Validation
+```typescript
+import { validateTemplate } from '@/lib/utils/path-template.util';
+
+// Valid templates
+validateTemplate('{author}/{title}');
+// { valid: true }
+
+validateTemplate('Audiobooks/{author}/{title}');
+// { valid: true }
+
+// Invalid templates
+validateTemplate('{author}/{invalid}');
+// { valid: false, error: "Unknown variable: {invalid}..." }
+
+validateTemplate('/absolute/path/{author}');
+// { valid: false, error: "Template must be a relative path..." }
+
+validateTemplate('{author}|{title}');
+// { valid: false, error: "Invalid characters found: |..." }
+```
+
+### Generate Previews
+```typescript
+import { generateMockPreviews } from '@/lib/utils/path-template.util';
+
+const previews = generateMockPreviews('{author}/{title}/{narrator}');
+// Returns 3 examples, including one without a narrator
+
+previews.forEach(preview => console.log(preview));
+// Brandon Sanderson/Mistborn The Final Empire/Michael Kramer
+// Douglas Adams/The Hitchhiker's Guide to the Galaxy/Stephen Fry
+// Andy Weir/Project Hail Mary
+```
+
+### Automatic Sanitization
+```typescript
+const result = substituteTemplate(
+  '{author}/{title}',
+  {
+    author: 'Author: <Test>',
+    title: 'Title|With*Invalid?Chars"'
+  }
+);
+// Result: "Author Test/TitleWithInvalidChars"
+// Invalid characters automatically removed
+```
+
+## Path Sanitization Rules
+
+The utility automatically sanitizes all substituted values:
+
+1. **Removes invalid characters:** `<`, `>`, `:`, `"`, `/`, `\`, `|`, `?`, `*`
+2. **Trims dots and spaces** from beginning and end
+3. **Collapses multiple spaces** into single space
+4. **Limits length** to 200 characters per component
+5. **Normalizes path separators** (converts `\` to `/`)
+
+## Integration Points
+
+### File Organizer Service
+The path template utility is used by `file-organizer.ts` to generate organized directory structures for downloaded audiobook files.
+
+### Test Paths API
+The utility is also used by the `/api/test-paths` endpoint to allow users to preview how their custom path templates will look before applying them.
+
+## Testing
+
+Comprehensive test suite located at: `tests/lib/utils/path-template.util.test.ts`
+
+Run tests:
+```bash
+npm test -- path-template
+```
+
+## Type Definitions
+
+```typescript
+interface TemplateVariables {
+  author: string;
+  title: string;
+  narrator?: string;
+  asin?: string;
+}
+
+interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+```

src/lib/utils/file-organizer.ts

@@ -21,6 +21,7 @@ import {
 } from './chapter-merger';
 import { prisma } from '../db';
 import { downloadEbook } from '../services/ebook-scraper';
+import { substituteTemplate, type TemplateVariables } from './path-template.util';
 
 export interface AudiobookMetadata {
   title: string;
@@ -66,6 +67,7 @@ export class FileOrganizer {
   async organize(
     downloadPath: string,
     audiobook: AudiobookMetadata,
+    template: string,
     loggerConfig?: LoggerConfig
   ): Promise<OrganizationResult> {
     // Create logger if config provided
@@ -268,10 +270,12 @@ export class FileOrganizer {
       // Build target directory
       const targetPath = this.buildTargetPath(
         this.mediaDir,
+        template,
         audiobook.author,
         audiobook.title,
-        audiobook.year,
-        audiobook.asin
+        audiobook.narrator,
+        audiobook.asin,
+        audiobook.year
       );
 
       await logger?.info(`Target path: ${targetPath}`);
@@ -542,31 +546,28 @@ export class FileOrganizer {
   }
 
   /**
-   * Build target path with sanitized names
-   * Format: Author/Title (Year) ASIN or Author/Title ASIN or Author/Title (Year)
+   * Build target path using template-based path building
+   * Uses the path template engine to substitute variables and sanitize paths
    */
   private buildTargetPath(
     baseDir: string,
+    template: string,
     author: string,
     title: string,
-    year?: number,
-    asin?: string
+    narrator?: string,
+    asin?: string,
+    year?: number
   ): string {
-    const authorClean = this.sanitizePath(author);
-    const titleClean = this.sanitizePath(title);
+    const variables: TemplateVariables = {
+      author,
+      title,
+      narrator,
+      asin,
+      year,
+    };
 
-    // Build folder name with optional year and ASIN
-    let folderName = titleClean;
-
-    if (year) {
-      folderName = `${folderName} (${year})`;
-    }
-
-    if (asin) {
-      folderName = `${folderName} ${asin}`;
-    }
-
-    return path.join(baseDir, authorClean, folderName);
+    const relativePath = substituteTemplate(template, variables);
+    return path.join(baseDir, relativePath);
   }
 
   /**
@@ -689,3 +690,39 @@ export async function getFileOrganizer(): Promise<FileOrganizer> {
 
   return new FileOrganizer(mediaDir, tempDir);
 }
+
+/**
+ * Build audiobook path using template-based path building
+ * Standalone function for use by other modules (e.g., fetch-ebook route, request-delete service)
+ *
+ * @param baseDir - Base directory for audiobooks (e.g., /media/audiobooks)
+ * @param template - Path template string (e.g., "{author}/{title} {asin}")
+ * @param variables - Object containing variable values (author, title, narrator, asin)
+ * @returns Full path to audiobook directory
+ *
+ * @example
+ * ```typescript
+ * const path = buildAudiobookPath(
+ *   '/media/audiobooks',
+ *   '{author}/{title} {asin}',
+ *   { author: 'Brandon Sanderson', title: 'Mistborn', asin: 'B002UZMLXM' }
+ * );
+ * // Returns: "/media/audiobooks/Brandon Sanderson/Mistborn B002UZMLXM"
+ * ```
+ */
+export function buildAudiobookPath(
+  baseDir: string,
+  template: string,
+  variables: { author: string; title: string; narrator?: string; asin?: string; year?: number }
+): string {
+  const templateVars: TemplateVariables = {
+    author: variables.author,
+    title: variables.title,
+    narrator: variables.narrator,
+    asin: variables.asin,
+    year: variables.year,
+  };
+
+  const relativePath = substituteTemplate(template, templateVars);
+  return path.join(baseDir, relativePath);
+}

src/lib/utils/path-template.util.ts

@@ -0,0 +1,259 @@
+/**
+ * Path Template Engine Utility
+ * Documentation: documentation/backend/services/file-organizer.md
+ *
+ * Provides template variable substitution, validation, and preview generation
+ * for audiobook file organization paths.
+ */
+
+/**
+ * Template variables for path substitution
+ */
+export interface TemplateVariables {
+  author: string;
+  title: string;
+  narrator?: string;
+  asin?: string;
+  year?: number;
+}
+
+/**
+ * Template validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+/**
+ * Supported template variable names
+ */
+const VALID_VARIABLES = ['author', 'title', 'narrator', 'asin', 'year'];
+
+/**
+ * Invalid file path characters (outside of template variables)
+ */
+const INVALID_PATH_CHARS = /[<>:"|?*]/;
+
+/**
+ * Sanitize a path component by removing invalid characters
+ * Reuses logic from file-organizer.ts
+ *
+ * @param name - Path component to sanitize
+ * @returns Sanitized path component
+ */
+function sanitizePath(name: string): string {
+  return (
+    name
+      // Remove invalid filename characters
+      .replace(/[<>:"/\\|?*]/g, '')
+      // Remove leading/trailing dots and spaces
+      .trim()
+      .replace(/^\.+/, '')
+      .replace(/\.+$/, '')
+      // Collapse multiple spaces
+      .replace(/\s+/g, ' ')
+      // Limit length (255 chars max for most filesystems)
+      .slice(0, 200)
+  );
+}
+
+/**
+ * Substitute template variables with actual values
+ *
+ * Supported variables: {author}, {title}, {narrator}, {asin}
+ * - Handles missing/null variables gracefully (omits them)
+ * - Applies path sanitization to all substituted values
+ * - Removes multiple consecutive spaces after substitution
+ *
+ * @param template - Path template string (e.g., "{author}/{title}")
+ * @param variables - Object containing variable values
+ * @returns Substituted and sanitized path string
+ *
+ * @example
+ * ```typescript
+ * const result = substituteTemplate(
+ *   "{author}/{title}",
+ *   { author: "Brandon Sanderson", title: "Mistborn" }
+ * );
+ * // Returns: "Brandon Sanderson/Mistborn"
+ * ```
+ */
+export function substituteTemplate(
+  template: string,
+  variables: TemplateVariables
+): string {
+  let result = template;
+
+  // Substitute each variable
+  for (const key of VALID_VARIABLES) {
+    const value = variables[key as keyof TemplateVariables];
+    const regex = new RegExp(`\\{${key}\\}`, 'g');
+
+    if (value !== undefined && value !== null) {
+      // Convert value to string and sanitize
+      const stringValue = String(value);
+      if (stringValue.trim()) {
+        const sanitizedValue = sanitizePath(stringValue.trim());
+        result = result.replace(regex, sanitizedValue);
+      } else {
+        // Remove the variable placeholder if value is empty
+        result = result.replace(regex, '');
+      }
+    } else {
+      // Remove the variable placeholder if value is missing
+      result = result.replace(regex, '');
+    }
+  }
+
+  // Clean up the result
+  result = result
+    // Remove multiple consecutive slashes (forward or backward)
+    .replace(/[\/\\]+/g, '/')
+    // Remove multiple consecutive spaces
+    .replace(/\s+/g, ' ')
+    // Remove leading/trailing slashes and spaces from each path component
+    .split('/')
+    .map(part => part.trim())
+    .filter(part => part.length > 0)
+    .join('/');
+
+  return result;
+}
+
+/**
+ * Validate a path template string
+ *
+ * Checks for:
+ * - Valid variable names only (rejects unknown variables)
+ * - No invalid file path characters outside of variables
+ * - Non-empty template
+ * - Relative paths only (no absolute paths)
+ *
+ * @param template - Path template string to validate
+ * @returns Validation result with error message if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateTemplate("{author}/{title}");
+ * // Returns: { valid: true }
+ *
+ * const invalid = validateTemplate("{invalid}/{title}");
+ * // Returns: { valid: false, error: "Unknown variable: {invalid}" }
+ * ```
+ */
+export function validateTemplate(template: string): ValidationResult {
+  // Check for empty template
+  if (!template || template.trim().length === 0) {
+    return {
+      valid: false,
+      error: 'Template cannot be empty'
+    };
+  }
+
+  // Check for absolute paths
+  if (template.startsWith('/') || template.startsWith('\\') || /^[a-zA-Z]:/.test(template)) {
+    return {
+      valid: false,
+      error: 'Template must be a relative path (no absolute paths like "/" or "C:\\")'
+    };
+  }
+
+  // Extract all variables from template
+  const variableMatches = template.match(/\{[^}]+\}/g);
+
+  if (variableMatches) {
+    for (const match of variableMatches) {
+      const varName = match.slice(1, -1); // Remove { and }
+
+      if (!VALID_VARIABLES.includes(varName)) {
+        return {
+          valid: false,
+          error: `Unknown variable: {${varName}}. Valid variables are: ${VALID_VARIABLES.map(v => `{${v}}`).join(', ')}`
+        };
+      }
+    }
+  }
+
+  // Remove valid variables temporarily to check for invalid characters
+  let templateWithoutVars = template;
+  for (const varName of VALID_VARIABLES) {
+    templateWithoutVars = templateWithoutVars.replace(new RegExp(`\\{${varName}\\}`, 'g'), '');
+  }
+
+  // Check for invalid characters outside of variables
+  const invalidChars = templateWithoutVars.match(INVALID_PATH_CHARS);
+  if (invalidChars) {
+    return {
+      valid: false,
+      error: `Invalid characters found: ${[...new Set(invalidChars)].join(', ')}. These characters are not allowed in path templates.`
+    };
+  }
+
+  // Check for backslashes (Windows-style paths)
+  if (templateWithoutVars.includes('\\')) {
+    return {
+      valid: false,
+      error: 'Use forward slashes (/) for path separators, not backslashes (\\)'
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Generate mock preview paths using sample audiobook data
+ *
+ * Creates 2-3 example paths to demonstrate how the template will look
+ * with real audiobook metadata.
+ *
+ * @param template - Path template string
+ * @returns Array of example paths (2-3 examples)
+ *
+ * @example
+ * ```typescript
+ * const previews = generateMockPreviews("{author}/{title}");
+ * // Returns:
+ * // [
+ * //   "Brandon Sanderson/Mistborn The Final Empire",
+ * //   "Douglas Adams/The Hitchhiker's Guide to the Galaxy",
+ * //   "Andy Weir/Project Hail Mary"
+ * // ]
+ * ```
+ */
+export function generateMockPreviews(template: string): string[] {
+  const mockData: TemplateVariables[] = [
+    {
+      author: 'Brandon Sanderson',
+      title: 'Mistborn: The Final Empire',
+      narrator: 'Michael Kramer',
+      asin: 'B002UZMLXM',
+      year: 2006
+    },
+    {
+      author: 'Douglas Adams',
+      title: "The Hitchhiker's Guide to the Galaxy",
+      narrator: 'Stephen Fry',
+      asin: 'B0009JKV9W',
+      year: 2005
+    },
+    {
+      author: 'Andy Weir',
+      title: 'Project Hail Mary',
+      // No narrator for this example
+      asin: 'B08G9PRS1K',
+      year: 2021
+    }
+  ];
+
+  return mockData.map(variables => substituteTemplate(template, variables));
+}
+
+/**
+ * Get list of valid template variable names
+ *
+ * @returns Array of valid variable names
+ */
+export function getValidVariables(): string[] {
+  return [...VALID_VARIABLES];
+}