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.
2026-06-03 21:00:09 +00:00 · 2026-01-16 13:47:36 -05:00
parent 428d9a12e0
commit 3a9ae4a439
59 changed files with 4043 additions and 256 deletions
@@ -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;
+}
+```
@@ -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);
+}
@@ -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];
+}