Add series fields to audiobooks and update related logic

Introduces 'series' and 'seriesPart' fields to the Audiobook model and database schema. Updates API routes, file organization, and path template utilities to support series metadata. Enhances chapter merging logic, improves notification backend testing, and expands test coverage for admin and API routes.

tests/components/bookdate/BookPickerModal.test.tsx

@@ -0,0 +1,158 @@
+/**
+ * Component: BookDate Book Picker Modal Tests
+ * Documentation: documentation/features/bookdate.md
+ */
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const books = [
+  { id: 'book-1', title: 'First Book', author: 'Author One', coverUrl: null },
+  { id: 'book-2', title: 'Second Book', author: 'Author Two', coverUrl: null },
+];
+
+describe('BookPickerModal', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    localStorage.clear();
+  });
+
+  it('loads books and confirms the selection', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ books }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    localStorage.setItem('accessToken', 'token-123');
+    const onConfirm = vi.fn();
+    const onClose = vi.fn();
+    const { BookPickerModal } = await import('@/components/bookdate/BookPickerModal');
+
+    render(
+      <BookPickerModal
+        isOpen={true}
+        onClose={onClose}
+        selectedIds={[]}
+        onConfirm={onConfirm}
+        maxSelection={5}
+      />
+    );
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith('/api/bookdate/library', {
+        headers: { Authorization: 'Bearer token-123' },
+      });
+    });
+
+    const firstBookButton = await screen.findByRole('button', { name: /First Book/ });
+    fireEvent.click(firstBookButton);
+
+    fireEvent.click(screen.getByRole('button', { name: /Confirm Selection/ }));
+
+    expect(onConfirm).toHaveBeenCalledWith(['book-1']);
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('disables additional selections once the max is reached', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ books }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    localStorage.setItem('accessToken', 'token-456');
+    const { BookPickerModal } = await import('@/components/bookdate/BookPickerModal');
+
+    render(
+      <BookPickerModal
+        isOpen={true}
+        onClose={vi.fn()}
+        selectedIds={[]}
+        onConfirm={vi.fn()}
+        maxSelection={1}
+      />
+    );
+
+    const firstBookButton = await screen.findByRole('button', { name: /First Book/ });
+    fireEvent.click(firstBookButton);
+
+    expect(screen.getByText(/Maximum reached/)).toBeInTheDocument();
+
+    const secondBookButton = screen.getByRole('button', { name: /Second Book/ });
+    expect(secondBookButton).toBeDisabled();
+  });
+
+  it('shows an error when loading books fails', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      json: async () => ({}),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    const { BookPickerModal } = await import('@/components/bookdate/BookPickerModal');
+
+    render(
+      <BookPickerModal
+        isOpen={true}
+        onClose={vi.fn()}
+        selectedIds={[]}
+        onConfirm={vi.fn()}
+        maxSelection={5}
+      />
+    );
+
+    expect(await screen.findByText('Failed to load library books')).toBeInTheDocument();
+  });
+
+  it('shows an empty search state when no books match', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ books }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    const { BookPickerModal } = await import('@/components/bookdate/BookPickerModal');
+
+    render(
+      <BookPickerModal
+        isOpen={true}
+        onClose={vi.fn()}
+        selectedIds={[]}
+        onConfirm={vi.fn()}
+        maxSelection={5}
+      />
+    );
+
+    await screen.findByRole('button', { name: /First Book/ });
+
+    fireEvent.change(screen.getByPlaceholderText('Search books...'), { target: { value: 'missing' } });
+
+    expect(screen.getByText('No books match your search')).toBeInTheDocument();
+  });
+
+  it('clears selection and disables confirm', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ books }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    const { BookPickerModal } = await import('@/components/bookdate/BookPickerModal');
+
+    render(
+      <BookPickerModal
+        isOpen={true}
+        onClose={vi.fn()}
+        selectedIds={['book-1']}
+        onConfirm={vi.fn()}
+        maxSelection={5}
+      />
+    );
+
+    await screen.findByRole('button', { name: /First Book/ });
+
+    const clearButton = screen.getByRole('button', { name: 'Clear Selection' });
+    fireEvent.click(clearButton);
+
+    expect(screen.getByRole('button', { name: /Confirm Selection/ })).toBeDisabled();
+  });
+});

tests/components/bookdate/CardStack.test.tsx

@@ -0,0 +1,89 @@
+/**
+ * Component: BookDate Card Stack Tests
+ * Documentation: documentation/features/bookdate-animations.md
+ */
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@/components/bookdate/RecommendationCard', () => ({
+  RecommendationCard: ({
+    recommendation,
+    onSwipe,
+    stackPosition,
+    isDraggable,
+  }: {
+    recommendation: { id: string; title: string };
+    onSwipe: (action: 'left' | 'right' | 'up') => void;
+    stackPosition: number;
+    isDraggable: boolean;
+  }) => (
+    <button
+      data-testid={`card-${recommendation.id}`}
+      data-stack={stackPosition}
+      data-draggable={String(isDraggable)}
+      onClick={() => onSwipe('left')}
+    >
+      {recommendation.title}
+    </button>
+  ),
+}));
+
+const recommendations = [
+  { id: 'rec-1', title: 'Rec One' },
+  { id: 'rec-2', title: 'Rec Two' },
+  { id: 'rec-3', title: 'Rec Three' },
+  { id: 'rec-4', title: 'Rec Four' },
+];
+
+describe('CardStack', () => {
+  it('renders up to three cards and only the top card is draggable', async () => {
+    const { CardStack } = await import('@/components/bookdate/CardStack');
+
+    render(
+      <CardStack
+        recommendations={recommendations}
+        currentIndex={0}
+        onSwipe={vi.fn()}
+        onSwipeComplete={vi.fn()}
+      />
+    );
+
+    expect(screen.getByTestId('card-rec-1')).toHaveAttribute('data-stack', '0');
+    expect(screen.getByTestId('card-rec-1')).toHaveAttribute('data-draggable', 'true');
+    expect(screen.getByTestId('card-rec-2')).toHaveAttribute('data-stack', '1');
+    expect(screen.getByTestId('card-rec-3')).toHaveAttribute('data-stack', '2');
+    expect(screen.queryByTestId('card-rec-4')).toBeNull();
+  });
+
+  it('locks swipes during animations and calls onSwipeComplete', async () => {
+    vi.useFakeTimers();
+    const onSwipe = vi.fn();
+    const onSwipeComplete = vi.fn();
+    const { CardStack } = await import('@/components/bookdate/CardStack');
+
+    render(
+      <CardStack
+        recommendations={recommendations}
+        currentIndex={0}
+        onSwipe={onSwipe}
+        onSwipeComplete={onSwipeComplete}
+      />
+    );
+
+    const topCard = screen.getByTestId('card-rec-1');
+    fireEvent.click(topCard);
+    fireEvent.click(topCard);
+
+    expect(onSwipe).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      vi.advanceTimersByTime(750);
+    });
+    expect(onSwipeComplete).toHaveBeenCalledTimes(1);
+    vi.useRealTimers();
+  });
+});

tests/components/bookdate/LoadingScreen.test.tsx

@@ -0,0 +1,25 @@
+/**
+ * Component: BookDate Loading Screen Tests
+ * Documentation: documentation/features/bookdate.md
+ */
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@/components/layout/Header', () => ({
+  Header: () => <div data-testid="header" />,
+}));
+
+describe('LoadingScreen', () => {
+  it('renders the loading message and header', async () => {
+    const { LoadingScreen } = await import('@/components/bookdate/LoadingScreen');
+
+    render(<LoadingScreen />);
+
+    expect(screen.getByTestId('header')).toBeInTheDocument();
+    expect(screen.getByText('Finding your next great listen...')).toBeInTheDocument();
+  });
+});

tests/components/bookdate/RecommendationCard.test.tsx

@@ -0,0 +1,135 @@
+/**
+ * Component: BookDate Recommendation Card Tests
+ * Documentation: documentation/features/bookdate.md
+ */
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const swipeHandlers: {
+  onSwiping?: (eventData: { deltaX: number; deltaY: number }) => void;
+  onSwiped?: (eventData: { deltaX: number; deltaY: number }) => void;
+} = {};
+
+vi.mock('react-swipeable', () => ({
+  useSwipeable: (handlers: any) => {
+    swipeHandlers.onSwiping = handlers.onSwiping;
+    swipeHandlers.onSwiped = handlers.onSwiped;
+    return {};
+  },
+}));
+
+const recommendation = {
+  title: 'Sample Book',
+  author: 'Sample Author',
+  narrator: 'Sample Narrator',
+  rating: 4.5,
+  description: 'A sample description',
+  aiReason: 'Because it matches your tastes.',
+};
+
+describe('RecommendationCard', () => {
+  beforeEach(() => {
+    swipeHandlers.onSwiping = undefined;
+    swipeHandlers.onSwiped = undefined;
+  });
+
+  it('shows the request toast and triggers a request action', async () => {
+    const onSwipe = vi.fn();
+    const { RecommendationCard } = await import('@/components/bookdate/RecommendationCard');
+
+    render(<RecommendationCard recommendation={recommendation} onSwipe={onSwipe} />);
+
+    const requestButtons = screen.getAllByRole('button', { name: /Request/ });
+    fireEvent.click(requestButtons[0]);
+
+    expect(screen.getByText('Request "Sample Book"?')).toBeInTheDocument();
+    const toastRequestButtons = screen.getAllByRole('button', { name: /Request/ });
+    fireEvent.click(toastRequestButtons[toastRequestButtons.length - 1]);
+
+    expect(onSwipe).toHaveBeenCalledWith('right', false);
+  });
+
+  it('marks a recommendation as liked from the toast', async () => {
+    const onSwipe = vi.fn();
+    const { RecommendationCard } = await import('@/components/bookdate/RecommendationCard');
+
+    render(<RecommendationCard recommendation={recommendation} onSwipe={onSwipe} />);
+
+    const requestButtons = screen.getAllByRole('button', { name: /Request/ });
+    fireEvent.click(requestButtons[0]);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Mark as Liked' }));
+
+    expect(onSwipe).toHaveBeenCalledWith('right', true);
+  });
+
+  it('triggers dislike and dismiss actions from desktop buttons', async () => {
+    const onSwipe = vi.fn();
+    const { RecommendationCard } = await import('@/components/bookdate/RecommendationCard');
+
+    render(<RecommendationCard recommendation={recommendation} onSwipe={onSwipe} />);
+
+    fireEvent.click(screen.getByRole('button', { name: /Not Interested/ }));
+    fireEvent.click(screen.getByRole('button', { name: /Dismiss/ }));
+
+    expect(onSwipe).toHaveBeenCalledWith('left');
+    expect(onSwipe).toHaveBeenCalledWith('up');
+  });
+
+  it('shows drag overlays based on swipe direction', async () => {
+    const onSwipe = vi.fn();
+    const { RecommendationCard } = await import('@/components/bookdate/RecommendationCard');
+
+    render(<RecommendationCard recommendation={recommendation} onSwipe={onSwipe} />);
+
+    act(() => {
+      swipeHandlers.onSwiping?.({ deltaX: -80, deltaY: 0 });
+    });
+
+    expect(screen.getByText('Dislike')).toBeInTheDocument();
+  });
+
+  it('triggers an upward swipe from gesture handling', async () => {
+    const onSwipe = vi.fn();
+    const { RecommendationCard } = await import('@/components/bookdate/RecommendationCard');
+
+    render(<RecommendationCard recommendation={recommendation} onSwipe={onSwipe} />);
+
+    act(() => {
+      swipeHandlers.onSwiped?.({ deltaX: 0, deltaY: -150 });
+    });
+
+    expect(onSwipe).toHaveBeenCalledWith('up');
+  });
+
+  it('ignores swipe gestures when not draggable', async () => {
+    const onSwipe = vi.fn();
+    const { RecommendationCard } = await import('@/components/bookdate/RecommendationCard');
+
+    render(
+      <RecommendationCard recommendation={recommendation} onSwipe={onSwipe} isDraggable={false} />
+    );
+
+    act(() => {
+      swipeHandlers.onSwiped?.({ deltaX: 150, deltaY: 0 });
+    });
+
+    expect(onSwipe).not.toHaveBeenCalled();
+    expect(screen.queryByText(/Request "Sample Book"/)).toBeNull();
+  });
+
+  it('hides desktop actions when not the top card', async () => {
+    const onSwipe = vi.fn();
+    const { RecommendationCard } = await import('@/components/bookdate/RecommendationCard');
+
+    render(
+      <RecommendationCard recommendation={recommendation} onSwipe={onSwipe} stackPosition={1} />
+    );
+
+    expect(screen.queryByRole('button', { name: /Not Interested/ })).toBeNull();
+  });
+});

tests/components/bookdate/SettingsWidget.test.tsx

@@ -0,0 +1,205 @@
+/**
+ * Component: BookDate Settings Widget Tests
+ * Documentation: documentation/features/bookdate.md
+ */
+
+// @vitest-environment jsdom
+
+import React from 'react';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@/components/bookdate/BookPickerModal', () => ({
+  BookPickerModal: ({ isOpen, onConfirm }: { isOpen: boolean; onConfirm: (ids: string[]) => void }) =>
+    isOpen ? (
+      <div data-testid="book-picker">
+        <button onClick={() => onConfirm(['book-1'])}>Select Book</button>
+      </div>
+    ) : null,
+}));
+
+describe('SettingsWidget', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    localStorage.clear();
+  });
+
+  it('loads preferences and populates the form', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        libraryScope: 'rated',
+        favoriteBookIds: ['book-1'],
+        customPrompt: 'Custom prompt',
+        backendCapabilities: { supportsRatings: true },
+      }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    localStorage.setItem('accessToken', 'token-789');
+    const { SettingsWidget } = await import('@/components/bookdate/SettingsWidget');
+
+    render(<SettingsWidget isOpen={true} onClose={vi.fn()} />);
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith('/api/bookdate/preferences', {
+        headers: { Authorization: 'Bearer token-789' },
+      });
+    });
+
+    const ratedRadio = await screen.findByRole('radio', { name: /Rated Books Only/ });
+    expect(ratedRadio).toBeChecked();
+    expect(screen.getByDisplayValue('Custom prompt')).toBeInTheDocument();
+  });
+
+  it('requires favorites selection before saving', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        libraryScope: 'full',
+        favoriteBookIds: [],
+        customPrompt: '',
+        backendCapabilities: { supportsRatings: true },
+      }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    localStorage.setItem('accessToken', 'token-000');
+    const { SettingsWidget } = await import('@/components/bookdate/SettingsWidget');
+
+    render(<SettingsWidget isOpen={true} onClose={vi.fn()} />);
+
+    const favoritesRadio = await screen.findByRole('radio', { name: /Pick my favorites/ });
+    fireEvent.click(favoritesRadio);
+    fireEvent.click(screen.getByRole('button', { name: /Save Preferences/ }));
+
+    expect(await screen.findByText('Please select at least 1 favorite book')).toBeInTheDocument();
+  });
+
+  it('saves onboarding preferences and calls completion handlers', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          libraryScope: 'full',
+          favoriteBookIds: [],
+          customPrompt: '',
+          backendCapabilities: { supportsRatings: true },
+        }),
+      })
+      .mockResolvedValueOnce({ ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+    localStorage.setItem('accessToken', 'token-onboarding');
+    const onClose = vi.fn();
+    const onOnboardingComplete = vi.fn();
+    const { SettingsWidget } = await import('@/components/bookdate/SettingsWidget');
+
+    render(
+      <SettingsWidget
+        isOpen={true}
+        onClose={onClose}
+        isOnboarding={true}
+        onOnboardingComplete={onOnboardingComplete}
+      />
+    );
+
+    const letsGoButton = await screen.findByRole('button', { name: "Let's Go!" });
+    vi.useFakeTimers();
+    fireEvent.click(letsGoButton);
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    const requestBody = JSON.parse(fetchMock.mock.calls[1][1].body as string);
+    expect(requestBody.onboardingComplete).toBe(true);
+    expect(requestBody.customPrompt).toBeNull();
+    expect(requestBody.libraryScope).toBe('full');
+
+    await act(async () => {
+      vi.advanceTimersByTime(500);
+    });
+
+    expect(onOnboardingComplete).toHaveBeenCalled();
+    expect(onClose).toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+
+  it('hides rated scope when backend does not support ratings', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        libraryScope: 'full',
+        favoriteBookIds: [],
+        customPrompt: '',
+        backendCapabilities: { supportsRatings: false },
+      }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    localStorage.setItem('accessToken', 'token-no-ratings');
+    const { SettingsWidget } = await import('@/components/bookdate/SettingsWidget');
+
+    render(<SettingsWidget isOpen={true} onClose={vi.fn()} />);
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalled();
+    });
+
+    expect(screen.queryByRole('radio', { name: /Rated Books Only/ })).toBeNull();
+  });
+
+  it('shows an error when loading preferences fails', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      json: async () => ({}),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    localStorage.setItem('accessToken', 'token-fail');
+    const { SettingsWidget } = await import('@/components/bookdate/SettingsWidget');
+
+    render(<SettingsWidget isOpen={true} onClose={vi.fn()} />);
+
+    expect(await screen.findByText('Failed to load preferences')).toBeInTheDocument();
+  });
+
+  it('saves preferences and clears success message after delay', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          libraryScope: 'full',
+          favoriteBookIds: [],
+          customPrompt: '',
+          backendCapabilities: { supportsRatings: true },
+        }),
+      })
+      .mockResolvedValueOnce({ ok: true, json: async () => ({}) });
+    vi.stubGlobal('fetch', fetchMock);
+    localStorage.setItem('accessToken', 'token-save');
+    const { SettingsWidget } = await import('@/components/bookdate/SettingsWidget');
+
+    render(<SettingsWidget isOpen={true} onClose={vi.fn()} />);
+
+    const promptInput = await screen.findByLabelText(/Special Requests/);
+    fireEvent.change(promptInput, { target: { value: '  trimmed  ' } });
+
+    vi.useFakeTimers();
+    fireEvent.click(screen.getByRole('button', { name: 'Save Preferences' }));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    const requestBody = JSON.parse(fetchMock.mock.calls[1][1].body as string);
+    expect(requestBody.customPrompt).toBe('trimmed');
+    expect(requestBody.onboardingComplete).toBeUndefined();
+
+    expect(screen.getByText('Preferences saved successfully!')).toBeInTheDocument();
+
+    await act(async () => {
+      vi.advanceTimersByTime(3000);
+    });
+
+    expect(screen.queryByText('Preferences saved successfully!')).toBeNull();
+    vi.useRealTimers();
+  });
+});