+
+ );
+
+ return createPortal(modalContent, document.body);
+}
diff --git a/src/components/admin/bulk-import/MatchReviewStep.tsx b/src/components/admin/bulk-import/MatchReviewStep.tsx
new file mode 100644
index 0000000..5bce97c
--- /dev/null
+++ b/src/components/admin/bulk-import/MatchReviewStep.tsx
@@ -0,0 +1,344 @@
+/**
+ * Component: Bulk Import - Match Review Step
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Scrollable list of discovered audiobooks with Audible matches,
+ * skip toggles, library status badges, and import controls.
+ */
+
+'use client';
+
+import React from 'react';
+import {
+ ArrowLeftIcon,
+ CheckCircleIcon,
+ ExclamationTriangleIcon,
+ MusicalNoteIcon,
+ XCircleIcon,
+} from '@heroicons/react/24/outline';
+import { CheckCircleIcon as CheckCircleSolid } from '@heroicons/react/24/solid';
+import { ScannedBook, formatBytes } from './types';
+
+interface MatchReviewStepProps {
+ books: ScannedBook[];
+ onToggleSkip: (index: number) => void;
+ onStartImport: () => void;
+ isImporting: boolean;
+ importResults: any;
+ onClose: () => void;
+ onBack: () => void;
+}
+
+function BookRow({
+ book,
+ onToggleSkip,
+}: {
+ book: ScannedBook;
+ onToggleSkip: () => void;
+}) {
+ const isDisabled = book.inLibrary || book.hasActiveRequest;
+ const isSkipped = book.skipped;
+ const hasMatch = book.match !== null;
+ const isLowConfidence = book.metadataSource === 'file_name';
+
+ return (
+ e.stopPropagation()}
+ >
+ {/* Header */}
+
+
+
+
+ {/* Step Indicator */}
+
+
+
+ + Bulk Import +
+
+ {STEP_ORDER.map((s, i) => (
+
+ {i > 0 && (
+
+ )}
+
+ ))}
+
+
+ {/* Content */}
+
+
+
+ {i < currentStepIndex ? (
+
+ ) : (
+ i + 1
+ )}
+
+
+ {STEP_LABELS[s]}
+
+
+ {step === 'select_folder' && (
+ selectedRootPath && handleFolderSelected(selectedRootPath)}
+ onBack={handleBackToFolderSelect}
+ />
+ )}
+
+ {step === 'review' && (
+
+
+ {/* Cover Art */}
+
+ );
+}
+
+export function MatchReviewStep({
+ books,
+ onToggleSkip,
+ onStartImport,
+ isImporting,
+ importResults,
+ onClose,
+ onBack,
+}: MatchReviewStepProps) {
+ const toImport = books.filter((b) => !b.skipped && b.match !== null);
+ const skippedCount = books.filter((b) => b.skipped).length;
+ const inLibraryCount = books.filter((b) => b.inLibrary).length;
+ const noMatchCount = books.filter((b) => b.match === null).length;
+ const matchedCount = books.filter((b) => b.match !== null).length;
+
+ // Import completed state
+ if (importResults) {
+ const succeeded = importResults.summary?.succeeded || 0;
+ const failed = importResults.summary?.failed || 0;
+
+ return (
+
+ {hasMatch && book.match!.coverArtUrl ? (
+ /* eslint-disable-next-line @next/next/no-img-element */
+ 
{
+ (e.target as HTMLImageElement).src = '/placeholder_cover.svg';
+ }}
+ />
+ ) : (
+
+
+ {/* Book Info */}
+
+
+ )}
+
+ {hasMatch ? (
+ <>
+
+
+ {/* Badges */}
+
+
+ + {book.match!.title} +
+ {isLowConfidence && ( + + Low Confidence + + )} ++ {book.match!.author} + {book.match!.narrator && ( + + {' '}· {book.match!.narrator} + + )} +
+ + ) : ( + <> +
+
+ + {book.folderName} +
+ + No Match + ++ Could not find this title on Audible +
+ + )} ++ {book.relativePath} +
+
+ {/* Audio file count */}
+
+
+
+ {/* Skip Toggle */}
+
+
+ {importResults.success !== false ? (
+ <>
+
+ );
+ }
+
+ // Empty state (no audiobooks found)
+ if (books.length === 0) {
+ return (
+ + Import Started +
++ {succeeded} audiobook{succeeded !== 1 ? 's' : ''} queued for import. +
+ {failed > 0 && ( ++ {failed} book{failed !== 1 ? 's' : ''} could not be queued. +
+ )} ++ Files will be organized, tagged, and imported into your library. Check the admin + dashboard for progress. +
+ + + ) : ( + <> ++ Import Failed +
++ {importResults.error || 'An unexpected error occurred'} +
+ + + )} +
+
+ );
+ }
+
+ return (
+ + No Audiobooks Found +
++ The selected folder does not contain any folders with audio files. Try selecting a + different folder. +
+ +
+ {/* Summary header */}
+
+ );
+}
diff --git a/src/components/admin/bulk-import/ScanFolderStep.tsx b/src/components/admin/bulk-import/ScanFolderStep.tsx
new file mode 100644
index 0000000..fb63645
--- /dev/null
+++ b/src/components/admin/bulk-import/ScanFolderStep.tsx
@@ -0,0 +1,346 @@
+/**
+ * Component: Bulk Import - Folder Selection Step
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Filesystem browser for selecting a root folder to scan for audiobooks.
+ * Adapted from the manual import BrowsePhase patterns.
+ * Any folder is selectable (not just audio-containing folders).
+ */
+
+'use client';
+
+import React, { useState, useEffect, useCallback } from 'react';
+import {
+ FolderIcon,
+ FolderOpenIcon,
+ FolderArrowDownIcon,
+ InboxArrowDownIcon,
+ HomeIcon,
+ ChevronRightIcon,
+ ArrowLeftIcon,
+ MusicalNoteIcon,
+ ExclamationTriangleIcon,
+ ArrowPathIcon,
+ MagnifyingGlassIcon,
+} from '@heroicons/react/24/outline';
+import { fetchWithAuth } from '@/lib/utils/api';
+import { RootEntry, DirectoryEntry, formatBytes } from './types';
+
+function SkeletonRow() {
+ return (
+
+
+
+ {/* Scrollable book list */}
+
+
+ {books.length} discovered
+
+ ·
+
+ {matchedCount} matched
+
+ {noMatchCount > 0 && (
+ <>
+ ·
+
+ {noMatchCount} unmatched
+
+
+ )}
+ {inLibraryCount > 0 && (
+ <>
+ ·
+
+ {inLibraryCount} in library
+
+
+ )}
+
+
+ {books.map((book) => (
+ onToggleSkip(book.index)}
+ />
+ ))}
+
+
+ {/* Import footer */}
+
+
+
+
+
+
+
+ {toImport.length}
+ {' '}
+ book{toImport.length !== 1 ? 's' : ''} to import
+ {skippedCount > 0 && (
+
+ {' '}({skippedCount} skipped)
+
+ )}
+
+
+
+
+
+
+
+ );
+}
+
+interface ScanFolderStepProps {
+ onFolderSelected: (rootPath: string) => void;
+}
+
+export function ScanFolderStep({ onFolderSelected }: ScanFolderStepProps) {
+ const [roots, setRoots] = useState
+
+
+
+
+ {/* Breadcrumb bar */}
+ {currentPath && (
+
+ );
+}
diff --git a/src/components/admin/bulk-import/ScanProgressStep.tsx b/src/components/admin/bulk-import/ScanProgressStep.tsx
new file mode 100644
index 0000000..169f44b
--- /dev/null
+++ b/src/components/admin/bulk-import/ScanProgressStep.tsx
@@ -0,0 +1,179 @@
+/**
+ * Component: Bulk Import - Scan Progress Step
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Displays progress during folder discovery and Audible matching phases.
+ * Shows animated indicators, counts, and cancel/retry controls.
+ */
+
+'use client';
+
+import React from 'react';
+import {
+ FolderIcon,
+ ExclamationTriangleIcon,
+ ArrowPathIcon,
+ ArrowLeftIcon,
+ XMarkIcon,
+} from '@heroicons/react/24/outline';
+import { ScanProgressEvent, MatchingProgressEvent } from './types';
+
+interface ScanProgressStepProps {
+ scanProgress: ScanProgressEvent | null;
+ matchingProgress: MatchingProgressEvent | null;
+ scanPhase: 'discovering' | 'matching' | 'idle';
+ error: string | null;
+ booksFound: number;
+ onCancel: () => void;
+ onRetry: () => void;
+ onBack: () => void;
+}
+
+export function ScanProgressStep({
+ scanProgress,
+ matchingProgress,
+ scanPhase,
+ error,
+ booksFound,
+ onCancel,
+ onRetry,
+ onBack,
+}: ScanProgressStepProps) {
+ // Error state
+ if (error) {
+ return (
+
+
+ {visibleBreadcrumbs.map((crumb, i) => (
+
+
+ ))}
+
+ )}
+
+ {/* Listing */}
+
+ {/* Loading */}
+ {isLoading && (
+
+
+ {/* Footer: Scan this folder */}
+ {currentPath && !isLoading && (
+
+ {[...Array(5)].map((_, i) => (
+
+ )}
+
+ {/* Error */}
+ {error && !isLoading && (
+
+
+ )}
+
+ {/* Root view */}
+ {!currentPath && !isLoading && !error && (
+ {error}
+ +
+
+ )}
+
+ {/* Directory listing */}
+ {currentPath && !isLoading && !error && entries.length > 0 && (
+ + Select a folder to scan for audiobooks. All subfolders will be searched recursively. +
+
+ {roots.map((root) => (
+
+ ))}
+
+
+ {entries.map((entry) => {
+ const hasAudio = entry.audioFileCount > 0;
+ const isHovered = hoveredFolder === entry.name;
+
+ return (
+
+ );
+ })}
+
+ )}
+
+ {/* Empty state */}
+ {currentPath && !isLoading && !error && entries.length === 0 && (
+
+
+ )}
+ This folder is empty
+ +
+
+ )}
+
+
+
+ {currentPath}
+ {entries.length > 0 && ( ++ {entries.length} subfolder{entries.length !== 1 ? 's' : ''} + {totalAudioInChildren > 0 && ( + · {totalAudioInChildren} audio files visible + )} +
+ )} +
+
+ );
+ }
+
+ const matchPercent = matchingProgress
+ ? Math.round((matchingProgress.current / matchingProgress.total) * 100)
+ : 0;
+
+ return (
+ + Scan Failed +
++ {error} +
+
+
+
+
+
+ {/* Animated icon */}
+
+ );
+}
diff --git a/src/components/admin/bulk-import/types.ts b/src/components/admin/bulk-import/types.ts
new file mode 100644
index 0000000..f441b6b
--- /dev/null
+++ b/src/components/admin/bulk-import/types.ts
@@ -0,0 +1,81 @@
+/**
+ * Component: Bulk Import Shared Types
+ * Documentation: documentation/features/bulk-import.md
+ */
+
+/** Root directory entry from the filesystem browse API. */
+export interface RootEntry {
+ name: string;
+ path: string;
+ icon: string;
+}
+
+/** Directory entry from the filesystem browse API. */
+export interface DirectoryEntry {
+ name: string;
+ type: 'directory';
+ audioFileCount: number;
+ subfolderCount: number;
+ totalSize: number;
+}
+
+/** Audible match data for a discovered audiobook. */
+export interface AudibleMatch {
+ asin: string;
+ title: string;
+ author: string;
+ narrator?: string;
+ coverArtUrl?: string;
+ durationMinutes?: number;
+}
+
+/** A scanned audiobook result with its Audible match status. */
+export interface ScannedBook {
+ index: number;
+ folderPath: string;
+ folderName: string;
+ relativePath: string;
+ audioFileCount: number;
+ totalSizeBytes: number;
+ metadataSource: 'tags' | 'file_name';
+ searchTerm: string;
+ match: AudibleMatch | null;
+ inLibrary: boolean;
+ hasActiveRequest: boolean;
+ /** User toggle: true = skip this book during import. */
+ skipped: boolean;
+}
+
+/** Progress event from the SSE scan stream. */
+export interface ScanProgressEvent {
+ phase: 'discovering' | 'reading_metadata';
+ foldersScanned: number;
+ audiobooksFound: number;
+ currentFolder?: string;
+}
+
+/** Matching progress event from the SSE scan stream. */
+export interface MatchingProgressEvent {
+ current: number;
+ total: number;
+ folderName: string;
+ searchTerm: string;
+}
+
+/** Discovery complete event from the SSE scan stream. */
+export interface DiscoveryCompleteEvent {
+ totalFound: number;
+ message: string;
+}
+
+/** Wizard step identifiers. */
+export type WizardStep = 'select_folder' | 'scanning' | 'review';
+
+/** Format bytes into a human-readable string. */
+export function formatBytes(bytes: number): string {
+ if (bytes === 0) return '0 B';
+ const k = 1024;
+ const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+ const i = Math.floor(Math.log(bytes) / Math.log(k));
+ return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
diff --git a/src/lib/utils/bulk-import-scanner.ts b/src/lib/utils/bulk-import-scanner.ts
new file mode 100644
index 0000000..00ff058
--- /dev/null
+++ b/src/lib/utils/bulk-import-scanner.ts
@@ -0,0 +1,294 @@
+/**
+ * Component: Bulk Import Scanner Utility
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Recursively discovers audiobook folders, reads embedded metadata via ffprobe,
+ * and prepares search terms for Audible matching. Used by the bulk import API.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import fs from 'fs/promises';
+import { AUDIO_EXTENSIONS } from '../constants/audio-formats';
+
+const execPromise = promisify(exec);
+
+/** Maximum recursion depth for folder scanning. */
+export const MAX_SCAN_DEPTH = 10;
+
+/** Metadata extracted from an audio file via ffprobe. */
+export interface AudioFileMetadata {
+ title?: string; // From 'album' tag (book title)
+ author?: string; // From 'album_artist' tag
+ narrator?: string; // From 'composer' tag
+ contributingArtists?: string; // From 'artist' tag (contributing artists)
+ trackTitle?: string; // From 'title' tag (chapter/track name)
+}
+
+/** A discovered audiobook folder with its metadata and file info. */
+export interface DiscoveredAudiobook {
+ folderPath: string;
+ folderName: string;
+ relativePath: string; // Relative to scan root
+ audioFileCount: number;
+ totalSizeBytes: number;
+ metadata: AudioFileMetadata;
+ searchTerm: string; // Constructed search query for Audible
+ metadataSource: 'tags' | 'file_name'; // Where the search term came from
+}
+
+/** Progress callback for streaming updates to the caller. */
+export interface ScanProgress {
+ phase: 'discovering' | 'reading_metadata';
+ foldersScanned: number;
+ audiobooksFound: number;
+ currentFolder?: string;
+}
+
+/**
+ * Check if a file has a supported audio extension.
+ */
+function isAudioFile(filename: string): boolean {
+ const ext = path.extname(filename).toLowerCase();
+ return (AUDIO_EXTENSIONS as readonly string[]).includes(ext);
+}
+
+/**
+ * Read audio metadata from a file using ffprobe.
+ * Extracts album, album_artist, composer, and title tags.
+ * Returns empty metadata on any failure (non-blocking).
+ */
+export async function readAudioMetadata(filePath: string): Promise
+
+
+ {/* Phase-specific content */}
+ {scanPhase === 'discovering' && (
+ <>
+
+
+
+ + Scanning Folders +
++ Searching for folders containing audiobook files... +
+ + {scanProgress && ( +
+
+ )}
+
+ {scanProgress?.currentFolder && (
+
+
+
+
+ {scanProgress.foldersScanned}
+
+
+ Folders Scanned
+
+
+
+
+ {scanProgress.audiobooksFound}
+
+
+ Audiobooks Found
+
+ + {scanProgress.currentFolder} +
+ )} + + )} + + {scanPhase === 'matching' && ( + <> ++ Matching Against Audible +
++ Searching Audible for each discovered audiobook... +
+ + {matchingProgress && ( + <> + {/* Progress bar */} +
+
+
+
+
+
+
+ {matchingProgress.current} / {matchingProgress.total}
+
+
+ {matchingProgress.folderName && (
+ + {matchingProgress.folderName} +
+ )} + + {/* Books matched so far count */} + {booksFound > 0 && ( ++ {booksFound} book{booksFound !== 1 ? 's' : ''} matched so far +
+ )} + + )} + + )} + + {/* Cancel button */} + +