Implement EPUB export format

[frankbria]

Problem

User manual mentions EPUB export as a feature but it's not implemented. EPUB is essential for ebook distribution.

Current Behavior

• Only PDF and DOCX export available
• No EPUB option in export dialog

Expected Behavior

• EPUB format available in export dialog
• EPUB file properly structured for ereaders
• Metadata included (title, author, ISBN, etc.)
• Table of contents navigation works in ereaders
• Images and formatting preserved

Implementation Guidance

1. Research EPUB 3.0 specification
2. Use Python library like ebooklib for EPUB generation
3. Create EPUB service similar to existing export services
4. Add EPUB to export format options
5. Test output in multiple ereaders (Kindle, Kobo, Apple Books)

Files Likely Involved

• backend/app/services/export_service.py - Add EPUB export
• backend/app/services/epub_service.py - Create EPUB-specific service
• frontend/src/components/export/ExportDialog.tsx - Add EPUB option
• backend/requirements.txt - Add ebooklib dependency

Acceptance Criteria

• EPUB option appears in export dialog
• EPUB file generates successfully
• Metadata properly embedded
• Table of contents works in ereaders
• Formatting preserved in EPUB
• EPUB validates against EPUB 3.0 spec
• Tested in Kindle, Kobo, Apple Books
• Integration test verifies EPUB structure

Blocked by

Issue #59 (Add professional export templates)

[traycerai]

Plan

Observations

The codebase has a well-structured export system with PDF and DOCX formats already implemented. The file:backend/app/services/export_service.py contains the core export logic with methods like generate_pdf() and generate_docx(), while file:backend/app/api/endpoints/export.py provides REST endpoints. The frontend uses file:frontend/src/components/export/ExportOptionsModal.tsx and file:frontend/src/app/dashboard/books/[bookId]/export/page.tsx for the export UI. The system uses reportlab for PDF and python-docx for DOCX generation, with HTML content converted via html2text. Tests are comprehensive with both service-level and API endpoint tests. The architecture follows a clean separation of concerns with dedicated services, API endpoints, and frontend components.

Approach

The implementation will follow the existing export pattern by adding EPUB as a third format alongside PDF and DOCX. A new generate_epub() method will be added to ExportService using the ebooklib Python library (EPUB 3.0 compliant). The backend will add an /epub endpoint mirroring the existing /pdf and /docx endpoints. The frontend will extend the ExportFormat type to include 'epub', update the export UI components to display EPUB as an option, and add a corresponding exportEPUB() method to bookClient. This approach maintains consistency with the existing codebase patterns while adding comprehensive EPUB support with proper metadata, table of contents navigation, and formatting preservation.

Implementation Steps

1. Backend Dependencies

Add EPUB library to Python dependencies:

• Update file:backend/requirements.in to add ebooklib>=0.18 for EPUB 3.0 generation
• Run pip-compile requirements.in to update file:backend/requirements.txt
• Update file:backend/pyproject.toml to include ebooklib==0.18 in the dependencies list

2. Backend Service - EPUB Generation

Extend file:backend/app/services/export_service.py:

Add a new generate_epub() async method to the ExportService class that:

• Accepts book_data, chapters, and optional output_stream parameters (matching existing method signatures)
• Creates an EPUB book using ebooklib.epub.EpubBook()
• Sets metadata: title, author, language, identifier (ISBN if available), publisher, description
• Creates EPUB chapters from book chapters using ebooklib.epub.EpubHtml()
• Converts HTML content to XHTML-compliant format for EPUB
• Generates table of contents with ebooklib.epub.EpubNcx() and ebooklib.epub.EpubNav()
• Adds default CSS styling for consistent formatting across ereaders
• Handles nested chapter structure (subchapters) in TOC
• Writes EPUB to BytesIO stream and returns bytes
• Preserves formatting from HTML content (headings, paragraphs, emphasis)

Update the export_book() method:

• Add elif format.lower() == 'epub': condition
• Call generate_epub() with appropriate parameters
• Return the generated EPUB bytes

3. Backend API Endpoint

Add EPUB endpoint to file:backend/app/api/endpoints/export.py:

Create new @router.get("/epub") endpoint function export_book_epub():

• Accept book_id, current_user, include_empty_chapters parameters
• Apply same rate limiting as PDF/DOCX (10 exports per hour)
• Verify book ownership (same pattern as existing endpoints)
• Log export access using chapter_access_service.log_access() with access_type="export_epub"
• Call export_service.export_book() with format="epub"
• Return StreamingResponse with MIME type application/epub+zip
• Set Content-Disposition header with sanitized filename ending in .epub
• Handle errors with appropriate HTTP status codes

Update get_export_formats() endpoint:

• Add EPUB format to the formats array with:
  • format: "epub"
  • name: "EPUB eBook"
  • description: "Electronic publication format - ideal for e-readers and mobile devices"
  • mime_type: "application/epub+zip"
  • extension: ".epub"
  • options: {"include_empty_chapters": "boolean"}

4. Frontend Types

Update file:frontend/src/types/export.ts:

• Change ExportFormat type from 'pdf' | 'docx' to 'pdf' | 'docx' | 'epub'

Update file:frontend/src/components/export/types.ts:

• Change ExportFormat type to include 'epub'

5. Frontend API Client

Extend file:frontend/src/lib/api/bookClient.ts:

Add new exportEPUB() method:

• Accept bookId and options?: { includeEmptyChapters?: boolean } parameters
• Build URLSearchParams with include_empty_chapters if provided
• Fetch from ${this.baseUrl}/books/${bookId}/export/epub?${params}
• Include authentication headers via getHeaders()
• Return response as Blob
• Handle errors with descriptive messages

6. Frontend Export UI Components

Update file:frontend/src/components/export/ExportOptionsModal.tsx:

Add EPUB option to the format selection RadioGroup:

• Create new RadioGroupItem with value="epub" and id="format-epub"
• Display "EPUB eBook" as the label
• Show description: "Electronic publication format - optimized for e-readers like Kindle, Kobo, and Apple Books"
• Use appropriate icon (e.g., book icon with different color)
• EPUB format should not show page size options (only includeEmptyChapters)

Update file:frontend/src/app/dashboard/books/[bookId]/export/page.tsx:

Extend the handleExport() function:

• Add else if (selectedFormat === 'epub') condition
• Call bookClient.exportEPUB(bookId, { includeEmptyChapters })
• Handle the returned blob same as PDF/DOCX

Update format icons mapping:

• Add EPUB icon (e.g., '📚' or '📖') in the formatsWithIcons mapping

7. Frontend Export Helpers

Update file:frontend/src/components/export/exportHelpers.ts:

• Modify format validation to accept 'epub' in addition to 'pdf' and 'docx'
• Update any format-specific logic to handle EPUB

8. Frontend Performance Tracking

Update file:frontend/src/lib/loading/timeEstimator.ts:

Add EPUB export time estimates:

• Add 'export.epub' entry to operation profiles with:
  • base: 8000 (8 seconds base time)
  • perThousandWords: 1500 (1.5 seconds per 1000 words)
  • perChapter: 800 (0.8 seconds per chapter)
  • min: 5000, max: 60000

Update file:frontend/src/lib/performance/budgets.ts:

Add EPUB export performance budget:

• Add 'export-epub' entry with:
  • name: 'export-epub'
  • target: 5000
  • warningThreshold: 0.8
  • description: 'Export book to EPUB format'
  • priority: 1

9. Backend Tests

Update file:backend/tests/test_services/test_export_service.py:

Add EPUB-specific test methods:

• test_generate_epub(): Test basic EPUB generation, verify bytes start with b'PK' (ZIP signature)
• test_export_book_epub(): Test complete book export to EPUB format
• test_epub_metadata(): Verify metadata is properly embedded (title, author, etc.)
• test_epub_toc(): Verify table of contents structure is correct
• test_epub_with_nested_chapters(): Test subchapter handling in EPUB TOC
• Extend test_export_invalid_format() to ensure EPUB is recognized as valid

Update file:backend/tests/test_api/test_export_endpoints.py:

Add EPUB endpoint tests:

• test_export_epub_success(): Test successful EPUB export with proper MIME type
• test_export_epub_with_options(): Test EPUB export with include_empty_chapters option
• Update test_export_formats_endpoint() to verify EPUB appears in formats list
• Verify EPUB format has correct metadata (name, extension, MIME type)

10. Frontend Tests

Update file:frontend/src/components/export/ExportOptionsModal.test.tsx:

• Add test case for EPUB format selection
• Verify EPUB option appears in the format list
• Test that EPUB doesn't show page size options (unlike PDF)

Update file:frontend/src/__tests__/utils/exportUtils.test.tsx:

• Add EPUB format validation tests
• Test EPUB export helper functions

11. E2E Tests

Update file:frontend/tests/e2e/deployment/02-user-journey.spec.ts:

Add EPUB export test:

• Navigate to export page
• Select EPUB format
• Configure options (include empty chapters)
• Trigger export
• Verify download starts with correct filename (.epub extension)
• Verify download completes successfully
• Add performance budget check using PERFORMANCE_BUDGETS.EXPORT_EPUB

Update file:frontend/tests/e2e/page-objects/export.page.ts:

• Add EPUB-specific selectors and methods
• Add selectEpubFormat() method
• Add exportAsEpub() method

12. Documentation Updates

Update user-facing documentation:

• Update file:AUTO_AUTHOR_USER_MANUAL.md to move EPUB from "Future Features" to current features
• Update file:docs/export-functionality.md to include detailed EPUB export instructions
• Update file:AUTO_AUTHOR_GAP_ANALYSIS.md to mark EPUB export as implemented

Architecture Diagram

sequenceDiagram
    participant User
    participant ExportUI as Export UI<br/>(page.tsx)
    participant BookClient as Book Client<br/>(bookClient.ts)
    participant ExportAPI as Export API<br/>(export.py)
    participant ExportService as Export Service<br/>(export_service.py)
    participant EbookLib as ebooklib

    User->>ExportUI: Select EPUB format
    User->>ExportUI: Configure options
    User->>ExportUI: Click "Export"
    
    ExportUI->>BookClient: exportEPUB(bookId, options)
    BookClient->>ExportAPI: GET /books/{id}/export/epub
    
    ExportAPI->>ExportAPI: Verify ownership
    ExportAPI->>ExportAPI: Log access
    ExportAPI->>ExportService: export_book(format="epub")
    
    ExportService->>ExportService: Flatten chapters
    ExportService->>ExportService: generate_epub()
    ExportService->>EbookLib: Create EpubBook
    ExportService->>EbookLib: Add metadata
    ExportService->>EbookLib: Add chapters
    ExportService->>EbookLib: Generate TOC
    ExportService->>EbookLib: Write EPUB
    
    EbookLib-->>ExportService: EPUB bytes
    ExportService-->>ExportAPI: EPUB bytes
    ExportAPI-->>BookClient: StreamingResponse (EPUB)
    BookClient-->>ExportUI: Blob
    
    ExportUI->>ExportUI: Create download link
    ExportUI->>User: Download EPUB file

Loading

Implementation Summary

Component	Files Modified	New Files	Tests Added
Backend Service	export_service.py	None	5 test methods
Backend API	export.py	None	3 test methods
Backend Dependencies	requirements.in, requirements.txt, pyproject.toml	None	N/A
Frontend Types	export.ts, types.ts	None	N/A
Frontend API	bookClient.ts	None	N/A
Frontend UI	ExportOptionsModal.tsx, page.tsx, exportHelpers.ts	None	2 test cases
Frontend Performance	timeEstimator.ts, budgets.ts	None	N/A
E2E Tests	02-user-journey.spec.ts, export.page.ts	None	1 test scenario
Documentation	AUTO_AUTHOR_USER_MANUAL.md, export-functionality.md, AUTO_AUTHOR_GAP_ANALYSIS.md	None	N/A

Total Estimated Effort: 8-10 hours

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-structured export system with PDF and DOCX formats already implemented. The `file:backend/app/services/export_service.py` contains the core export logic with methods like `generate_pdf()` and `generate_docx()`, while `file:backend/app/api/endpoints/export.py` provides REST endpoints. The frontend uses `file:frontend/src/components/export/ExportOptionsModal.tsx` and `file:frontend/src/app/dashboard/books/[bookId]/export/page.tsx` for the export UI. The system uses `reportlab` for PDF and `python-docx` for DOCX generation, with HTML content converted via `html2text`. Tests are comprehensive with both service-level and API endpoint tests. The architecture follows a clean separation of concerns with dedicated services, API endpoints, and frontend components.

## Approach

The implementation will follow the existing export pattern by adding EPUB as a third format alongside PDF and DOCX. A new `generate_epub()` method will be added to `ExportService` using the `ebooklib` Python library (EPUB 3.0 compliant). The backend will add an `/epub` endpoint mirroring the existing `/pdf` and `/docx` endpoints. The frontend will extend the `ExportFormat` type to include `'epub'`, update the export UI components to display EPUB as an option, and add a corresponding `exportEPUB()` method to `bookClient`. This approach maintains consistency with the existing codebase patterns while adding comprehensive EPUB support with proper metadata, table of contents navigation, and formatting preservation.

## Implementation Steps

### 1. Backend Dependencies

**Add EPUB library to Python dependencies:**

- Update `file:backend/requirements.in` to add `ebooklib>=0.18` for EPUB 3.0 generation
- Run `pip-compile requirements.in` to update `file:backend/requirements.txt`
- Update `file:backend/pyproject.toml` to include `ebooklib==0.18` in the dependencies list

### 2. Backend Service - EPUB Generation

**Extend `file:backend/app/services/export_service.py`:**

Add a new `generate_epub()` async method to the `ExportService` class that:
- Accepts `book_data`, `chapters`, and optional `output_stream` parameters (matching existing method signatures)
- Creates an EPUB book using `ebooklib.epub.EpubBook()`
- Sets metadata: title, author, language, identifier (ISBN if available), publisher, description
- Creates EPUB chapters from book chapters using `ebooklib.epub.EpubHtml()`
- Converts HTML content to XHTML-compliant format for EPUB
- Generates table of contents with `ebooklib.epub.EpubNcx()` and `ebooklib.epub.EpubNav()`
- Adds default CSS styling for consistent formatting across ereaders
- Handles nested chapter structure (subchapters) in TOC
- Writes EPUB to BytesIO stream and returns bytes
- Preserves formatting from HTML content (headings, paragraphs, emphasis)

Update the `export_book()` method:
- Add `elif format.lower() == 'epub':` condition
- Call `generate_epub()` with appropriate parameters
- Return the generated EPUB bytes

### 3. Backend API Endpoint

**Add EPUB endpoint to `file:backend/app/api/endpoints/export.py`:**

Create new `@router.get("/epub")` endpoint function `export_book_epub()`:
- Accept `book_id`, `current_user`, `include_empty_chapters` parameters
- Apply same rate limiting as PDF/DOCX (10 exports per hour)
- Verify book ownership (same pattern as existing endpoints)
- Log export access using `chapter_access_service.log_access()` with `access_type="export_epub"`
- Call `export_service.export_book()` with `format="epub"`
- Return `StreamingResponse` with MIME type `application/epub+zip`
- Set `Content-Disposition` header with sanitized filename ending in `.epub`
- Handle errors with appropriate HTTP status codes

Update `get_export_formats()` endpoint:
- Add EPUB format to the `formats` array with:
  - `format: "epub"`
  - `name: "EPUB eBook"`
  - `description: "Electronic publication format - ideal for e-readers and mobile devices"`
  - `mime_type: "application/epub+zip"`
  - `extension: ".epub"`
  - `options: {"include_empty_chapters": "boolean"}`

### 4. Frontend Types

**Update `file:frontend/src/types/export.ts`:**

- Change `ExportFormat` type from `'pdf' | 'docx'` to `'pdf' | 'docx' | 'epub'`

**Update `file:frontend/src/components/export/types.ts`:**

- Change `ExportFormat` type to include `'epub'`

### 5. Frontend API Client

**Extend `file:frontend/src/lib/api/bookClient.ts`:**

Add new `exportEPUB()` method:
- Accept `bookId` and `options?: { includeEmptyChapters?: boolean }` parameters
- Build URLSearchParams with `include_empty_chapters` if provided
- Fetch from `${this.baseUrl}/books/${bookId}/export/epub?${params}`
- Include authentication headers via `getHeaders()`
- Return response as `Blob`
- Handle errors with descriptive messages

### 6. Frontend Export UI Components

**Update `file:frontend/src/components/export/ExportOptionsModal.tsx`:**

Add EPUB option to the format selection RadioGroup:
- Create new RadioGroupItem with `value="epub"` and `id="format-epub"`
- Display "EPUB eBook" as the label
- Show description: "Electronic publication format - optimized for e-readers like Kindle, Kobo, and Apple Books"
- Use appropriate icon (e.g., book icon with different color)
- EPUB format should not show page size options (only `includeEmptyChapters`)

**Update `file:frontend/src/app/dashboard/books/[bookId]/export/page.tsx`:**

Extend the `handleExport()` function:
- Add `else if (selectedFormat === 'epub')` condition
- Call `bookClient.exportEPUB(bookId, { includeEmptyChapters })`
- Handle the returned blob same as PDF/DOCX

Update format icons mapping:
- Add EPUB icon (e.g., '📚' or '📖') in the `formatsWithIcons` mapping

### 7. Frontend Export Helpers

**Update `file:frontend/src/components/export/exportHelpers.ts`:**

- Modify format validation to accept `'epub'` in addition to `'pdf'` and `'docx'`
- Update any format-specific logic to handle EPUB

### 8. Frontend Performance Tracking

**Update `file:frontend/src/lib/loading/timeEstimator.ts`:**

Add EPUB export time estimates:
- Add `'export.epub'` entry to operation profiles with:
  - `base: 8000` (8 seconds base time)
  - `perThousandWords: 1500` (1.5 seconds per 1000 words)
  - `perChapter: 800` (0.8 seconds per chapter)
  - `min: 5000`, `max: 60000`

**Update `file:frontend/src/lib/performance/budgets.ts`:**

Add EPUB export performance budget:
- Add `'export-epub'` entry with:
  - `name: 'export-epub'`
  - `target: 5000`
  - `warningThreshold: 0.8`
  - `description: 'Export book to EPUB format'`
  - `priority: 1`

### 9. Backend Tests

**Update `file:backend/tests/test_services/test_export_service.py`:**

Add EPUB-specific test methods:
- `test_generate_epub()`: Test basic EPUB generation, verify bytes start with `b'PK'` (ZIP signature)
- `test_export_book_epub()`: Test complete book export to EPUB format
- `test_epub_metadata()`: Verify metadata is properly embedded (title, author, etc.)
- `test_epub_toc()`: Verify table of contents structure is correct
- `test_epub_with_nested_chapters()`: Test subchapter handling in EPUB TOC
- Extend `test_export_invalid_format()` to ensure EPUB is recognized as valid

**Update `file:backend/tests/test_api/test_export_endpoints.py`:**

Add EPUB endpoint tests:
- `test_export_epub_success()`: Test successful EPUB export with proper MIME type
- `test_export_epub_with_options()`: Test EPUB export with `include_empty_chapters` option
- Update `test_export_formats_endpoint()` to verify EPUB appears in formats list
- Verify EPUB format has correct metadata (name, extension, MIME type)

### 10. Frontend Tests

**Update `file:frontend/src/components/export/ExportOptionsModal.test.tsx`:**

- Add test case for EPUB format selection
- Verify EPUB option appears in the format list
- Test that EPUB doesn't show page size options (unlike PDF)

**Update `file:frontend/src/__tests__/utils/exportUtils.test.tsx`:**

- Add EPUB format validation tests
- Test EPUB export helper functions

### 11. E2E Tests

**Update `file:frontend/tests/e2e/deployment/02-user-journey.spec.ts`:**

Add EPUB export test:
- Navigate to export page
- Select EPUB format
- Configure options (include empty chapters)
- Trigger export
- Verify download starts with correct filename (`.epub` extension)
- Verify download completes successfully
- Add performance budget check using `PERFORMANCE_BUDGETS.EXPORT_EPUB`

**Update `file:frontend/tests/e2e/page-objects/export.page.ts`:**

- Add EPUB-specific selectors and methods
- Add `selectEpubFormat()` method
- Add `exportAsEpub()` method

### 12. Documentation Updates

**Update user-facing documentation:**

- Update `file:AUTO_AUTHOR_USER_MANUAL.md` to move EPUB from "Future Features" to current features
- Update `file:docs/export-functionality.md` to include detailed EPUB export instructions
- Update `file:AUTO_AUTHOR_GAP_ANALYSIS.md` to mark EPUB export as implemented

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ExportUI as Export UI<br/>(page.tsx)
    participant BookClient as Book Client<br/>(bookClient.ts)
    participant ExportAPI as Export API<br/>(export.py)
    participant ExportService as Export Service<br/>(export_service.py)
    participant EbookLib as ebooklib

    User->>ExportUI: Select EPUB format
    User->>ExportUI: Configure options
    User->>ExportUI: Click "Export"
    
    ExportUI->>BookClient: exportEPUB(bookId, options)
    BookClient->>ExportAPI: GET /books/{id}/export/epub
    
    ExportAPI->>ExportAPI: Verify ownership
    ExportAPI->>ExportAPI: Log access
    ExportAPI->>ExportService: export_book(format="epub")
    
    ExportService->>ExportService: Flatten chapters
    ExportService->>ExportService: generate_epub()
    ExportService->>EbookLib: Create EpubBook
    ExportService->>EbookLib: Add metadata
    ExportService->>EbookLib: Add chapters
    ExportService->>EbookLib: Generate TOC
    ExportService->>EbookLib: Write EPUB
    
    EbookLib-->>ExportService: EPUB bytes
    ExportService-->>ExportAPI: EPUB bytes
    ExportAPI-->>BookClient: StreamingResponse (EPUB)
    BookClient-->>ExportUI: Blob
    
    ExportUI->>ExportUI: Create download link
    ExportUI->>User: Download EPUB file
```

## Implementation Summary

| Component | Files Modified | New Files | Tests Added |
|-----------|---------------|-----------|-------------|
| Backend Service | `export_service.py` | None | 5 test methods |
| Backend API | `export.py` | None | 3 test methods |
| Backend Dependencies | `requirements.in`, `requirements.txt`, `pyproject.toml` | None | N/A |
| Frontend Types | `export.ts`, `types.ts` | None | N/A |
| Frontend API | `bookClient.ts` | None | N/A |
| Frontend UI | `ExportOptionsModal.tsx`, `page.tsx`, `exportHelpers.ts` | None | 2 test cases |
| Frontend Performance | `timeEstimator.ts`, `budgets.ts` | None | N/A |
| E2E Tests | `02-user-journey.spec.ts`, `export.page.ts` | None | 1 test scenario |
| Documentation | `AUTO_AUTHOR_USER_MANUAL.md`, `export-functionality.md`, `AUTO_AUTHOR_GAP_ANALYSIS.md` | None | N/A |

**Total Estimated Effort:** 8-10 hours

---

Execution Information

Branch: main
Commit: 7bfd621

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

_{You can configure auto-planning by selecting labels in the issue_enrichment configuration.}

🔗 Similar Issues

Related Issues

• Add professional export templates for PDF and DOCX #59
• Add error recovery mechanism to export functionality #49

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The codebase has a well-structured export system with PDF and DOCX formats already implemented. The file:backend/app/services/export_service.py contains the core export logic with methods like generate_pdf() and generate_docx(), while file:backend/app/api/endpoints/export.py provides REST endpoints. The frontend uses file:frontend/src/components/export/ExportOptionsModal.tsx and file:frontend/src/app/dashboard/books/[bookId]/export/page.tsx for the export UI. The system uses reportlab for PDF and python-docx for DOCX generation, with HTML content converted via html2text. Tests are comprehensive with both service-level and API endpoint tests. The architecture follows a clean separation of concerns with dedicated services, API endpoints, and frontend components.

Approach

The implementation will follow the existing export pattern by adding EPUB as a third format alongside PDF and DOCX. A new generate_epub() method will be added to ExportService using the ebooklib Python library (EPUB 3.0 compliant). The backend will add an /epub endpoint mirroring the existing /pdf and /docx endpoints. The frontend will extend the ExportFormat type to include 'epub', update the export UI components to display EPUB as an option, and add a corresponding exportEPUB() method to bookClient. This approach maintains consistency with the existing codebase patterns while adding comprehensive EPUB support with proper metadata, table of contents navigation, and formatting preservation.

Implementation Steps

1. Backend Dependencies

Add EPUB library to Python dependencies:

• Update file:backend/requirements.in to add ebooklib>=0.18 for EPUB 3.0 generation
• Run pip-compile requirements.in to update file:backend/requirements.txt
• Update file:backend/pyproject.toml to include ebooklib==0.18 in the dependencies list

2. Backend Service - EPUB Generation

Extend file:backend/app/services/export_service.py:

Add a new generate_epub() async method to the ExportService class that:

• Accepts book_data, chapters, and optional output_stream parameters (matching existing method signatures)
• Creates an EPUB book using ebooklib.epub.EpubBook()
• Sets metadata: title, author, language, identifier (ISBN if available), publisher, description
• Creates EPUB chapters from book chapters using ebooklib.epub.EpubHtml()
• Converts HTML content to XHTML-compliant format for EPUB
• Generates table of contents with ebooklib.epub.EpubNcx() and ebooklib.epub.EpubNav()
• Adds default CSS styling for consistent formatting across ereaders
• Handles nested chapter structure (subchapters) in TOC
• Writes EPUB to BytesIO stream and returns bytes
• Preserves formatting from HTML content (headings, paragraphs, emphasis)

Update the export_book() method:

• Add elif format.lower() == 'epub': condition
• Call generate_epub() with appropriate parameters
• Return the generated EPUB bytes

3. Backend API Endpoint

Add EPUB endpoint to file:backend/app/api/endpoints/export.py:

Create new @router.get("/epub") endpoint function export_book_epub():

• Accept book_id, current_user, include_empty_chapters parameters
• Apply same rate limiting as PDF/DOCX (10 exports per hour)
• Verify book ownership (same pattern as existing endpoints)
• Log export access using chapter_access_service.log_access() with access_type="export_epub"
• Call export_service.export_book() with format="epub"
• Return StreamingResponse with MIME type application/epub+zip
• Set Content-Disposition header with sanitized filename ending in .epub
• Handle errors with appropriate HTTP status codes

Update get_export_formats() endpoint:

• Add EPUB format to the formats array with:
  • format: "epub"
  • name: "EPUB eBook"
  • description: "Electronic publication format - ideal for e-readers and mobile devices"
  • mime_type: "application/epub+zip"
  • extension: ".epub"
  • options: {"include_empty_chapters": "boolean"}

4. Frontend Types

Update file:frontend/src/types/export.ts:

• Change ExportFormat type from 'pdf' | 'docx' to 'pdf' | 'docx' | 'epub'

Update file:frontend/src/components/export/types.ts:

• Change ExportFormat type to include 'epub'

5. Frontend API Client

Extend file:frontend/src/lib/api/bookClient.ts:

Add new exportEPUB() method:

• Accept bookId and options?: { includeEmptyChapters?: boolean } parameters
• Build URLSearchParams with include_empty_chapters if provided
• Fetch from ${this.baseUrl}/books/${bookId}/export/epub?${params}
• Include authentication headers via getHeaders()
• Return response as Blob
• Handle errors with descriptive messages

6. Frontend Export UI Components

Update file:frontend/src/components/export/ExportOptionsModal.tsx:

Add EPUB option to the format selection RadioGroup:

• Create new RadioGroupItem with value="epub" and id="format-epub"
• Display "EPUB eBook" as the label
• Show description: "Electronic publication format - optimized for e-readers like Kindle, Kobo, and Apple Books"
• Use appropriate icon (e.g., book icon with different color)
• EPUB format should not show page size options (only includeEmptyChapters)

Update file:frontend/src/app/dashboard/books/[bookId]/export/page.tsx:

Extend the handleExport() function:

• Add else if (selectedFormat === 'epub') condition
• Call bookClient.exportEPUB(bookId, { includeEmptyChapters })
• Handle the returned blob same as PDF/DOCX

Update format icons mapping:

• Add EPUB icon (e.g., '📚' or '📖') in the formatsWithIcons mapping

7. Frontend Export Helpers

Update file:frontend/src/components/export/exportHelpers.ts:

• Modify format validation to accept 'epub' in addition to 'pdf' and 'docx'
• Update any format-specific logic to handle EPUB

8. Frontend Performance Tracking

Update file:frontend/src/lib/loading/timeEstimator.ts:

Add EPUB export time estimates:

• Add 'export.epub' entry to operation profiles with:
  • base: 8000 (8 seconds base time)
  • perThousandWords: 1500 (1.5 seconds per 1000 words)
  • perChapter: 800 (0.8 seconds per chapter)
  • min: 5000, max: 60000

Update file:frontend/src/lib/performance/budgets.ts:

Add EPUB export performance budget:

• Add 'export-epub' entry with:
  • name: 'export-epub'
  • target: 5000
  • warningThreshold: 0.8
  • description: 'Export book to EPUB format'
  • priority: 1

9. Backend Tests

Update file:backend/tests/test_services/test_export_service.py:

Add EPUB-specific test methods:

• test_generate_epub(): Test basic EPUB generation, verify bytes start with b'PK' (ZIP signature)
• test_export_book_epub(): Test complete book export to EPUB format
• test_epub_metadata(): Verify metadata is properly embedded (title, author, etc.)
• test_epub_toc(): Verify table of contents structure is correct
• test_epub_with_nested_chapters(): Test subchapter handling in EPUB TOC
• Extend test_export_invalid_format() to ensure EPUB is recognized as valid

Update file:backend/tests/test_api/test_export_endpoints.py:

Add EPUB endpoint tests:

• test_export_epub_success(): Test successful EPUB export with proper MIME type
• test_export_epub_with_options(): Test EPUB export with include_empty_chapters option
• Update test_export_formats_endpoint() to verify EPUB appears in formats list
• Verify EPUB format has correct metadata (name, extension, MIME type)

10. Frontend Tests

Update file:frontend/src/components/export/ExportOptionsModal.test.tsx:

• Add test case for EPUB format selection
• Verify EPUB option appears in the format list
• Test that EPUB doesn't show page size options (unlike PDF)

Update file:frontend/src/__tests__/utils/exportUtils.test.tsx:

• Add EPUB format validation tests
• Test EPUB export helper functions

11. E2E Tests

Update file:frontend/tests/e2e/deployment/02-user-journey.spec.ts:

Add EPUB export test:

• Navigate to export page
• Select EPUB format
• Configure options (include empty chapters)
• Trigger export
• Verify download starts with correct filename (.epub extension)
• Verify download completes successfully
• Add performance budget check using PERFORMANCE_BUDGETS.EXPORT_EPUB

Update file:frontend/tests/e2e/page-objects/export.page.ts:

• Add EPUB-specific selectors and methods
• Add selectEpubFormat() method
• Add exportAsEpub() method

12. Documentation Updates

Update user-facing documentation:

• Update file:AUTO_AUTHOR_USER_MANUAL.md to move EPUB from "Future Features" to current features
• Update file:docs/export-functionality.md to include detailed EPUB export instructions
• Update file:AUTO_AUTHOR_GAP_ANALYSIS.md to mark EPUB export as implemented

Architecture Diagram

sequenceDiagram
    participant User
    participant ExportUI as Export UI<br/>(page.tsx)
    participant BookClient as Book Client<br/>(bookClient.ts)
    participant ExportAPI as Export API<br/>(export.py)
    participant ExportService as Export Service<br/>(export_service.py)
    participant EbookLib as ebooklib

    User->>ExportUI: Select EPUB format
    User->>ExportUI: Configure options
    User->>ExportUI: Click "Export"
    
    ExportUI->>BookClient: exportEPUB(bookId, options)
    BookClient->>ExportAPI: GET /books/{id}/export/epub
    
    ExportAPI->>ExportAPI: Verify ownership
    ExportAPI->>ExportAPI: Log access
    ExportAPI->>ExportService: export_book(format="epub")
    
    ExportService->>ExportService: Flatten chapters
    ExportService->>ExportService: generate_epub()
    ExportService->>EbookLib: Create EpubBook
    ExportService->>EbookLib: Add metadata
    ExportService->>EbookLib: Add chapters
    ExportService->>EbookLib: Generate TOC
    ExportService->>EbookLib: Write EPUB
    
    EbookLib-->>ExportService: EPUB bytes
    ExportService-->>ExportAPI: EPUB bytes
    ExportAPI-->>BookClient: StreamingResponse (EPUB)
    BookClient-->>ExportUI: Blob
    
    ExportUI->>ExportUI: Create download link
    ExportUI->>User: Download EPUB file

Loading

Implementation Summary

Component	Files Modified	New Files	Tests Added
Backend Service	export_service.py	None	5 test methods
Backend API	export.py	None	3 test methods
Backend Dependencies	requirements.in, requirements.txt, pyproject.toml	None	N/A
Frontend Types	export.ts, types.ts	None	N/A
Frontend API	bookClient.ts	None	N/A
Frontend UI	ExportOptionsModal.tsx, page.tsx, exportHelpers.ts	None	2 test cases
Frontend Performance	timeEstimator.ts, budgets.ts	None	N/A
E2E Tests	02-user-journey.spec.ts, export.page.ts	None	1 test scenario
Documentation	AUTO_AUTHOR_USER_MANUAL.md, export-functionality.md, AUTO_AUTHOR_GAP_ANALYSIS.md	None	N/A

Total Estimated Effort: 8-10 hours

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-structured export system with PDF and DOCX formats already implemented. The `file:backend/app/services/export_service.py` contains the core export logic with methods like `generate_pdf()` and `generate_docx()`, while `file:backend/app/api/endpoints/export.py` provides REST endpoints. The frontend uses `file:frontend/src/components/export/ExportOptionsModal.tsx` and `file:frontend/src/app/dashboard/books/[bookId]/export/page.tsx` for the export UI. The system uses `reportlab` for PDF and `python-docx` for DOCX generation, with HTML content converted via `html2text`. Tests are comprehensive with both service-level and API endpoint tests. The architecture follows a clean separation of concerns with dedicated services, API endpoints, and frontend components.

## Approach

The implementation will follow the existing export pattern by adding EPUB as a third format alongside PDF and DOCX. A new `generate_epub()` method will be added to `ExportService` using the `ebooklib` Python library (EPUB 3.0 compliant). The backend will add an `/epub` endpoint mirroring the existing `/pdf` and `/docx` endpoints. The frontend will extend the `ExportFormat` type to include `'epub'`, update the export UI components to display EPUB as an option, and add a corresponding `exportEPUB()` method to `bookClient`. This approach maintains consistency with the existing codebase patterns while adding comprehensive EPUB support with proper metadata, table of contents navigation, and formatting preservation.

## Implementation Steps

### 1. Backend Dependencies

**Add EPUB library to Python dependencies:**

- Update `file:backend/requirements.in` to add `ebooklib>=0.18` for EPUB 3.0 generation
- Run `pip-compile requirements.in` to update `file:backend/requirements.txt`
- Update `file:backend/pyproject.toml` to include `ebooklib==0.18` in the dependencies list

### 2. Backend Service - EPUB Generation

**Extend `file:backend/app/services/export_service.py`:**

Add a new `generate_epub()` async method to the `ExportService` class that:
- Accepts `book_data`, `chapters`, and optional `output_stream` parameters (matching existing method signatures)
- Creates an EPUB book using `ebooklib.epub.EpubBook()`
- Sets metadata: title, author, language, identifier (ISBN if available), publisher, description
- Creates EPUB chapters from book chapters using `ebooklib.epub.EpubHtml()`
- Converts HTML content to XHTML-compliant format for EPUB
- Generates table of contents with `ebooklib.epub.EpubNcx()` and `ebooklib.epub.EpubNav()`
- Adds default CSS styling for consistent formatting across ereaders
- Handles nested chapter structure (subchapters) in TOC
- Writes EPUB to BytesIO stream and returns bytes
- Preserves formatting from HTML content (headings, paragraphs, emphasis)

Update the `export_book()` method:
- Add `elif format.lower() == 'epub':` condition
- Call `generate_epub()` with appropriate parameters
- Return the generated EPUB bytes

### 3. Backend API Endpoint

**Add EPUB endpoint to `file:backend/app/api/endpoints/export.py`:**

Create new `@router.get("/epub")` endpoint function `export_book_epub()`:
- Accept `book_id`, `current_user`, `include_empty_chapters` parameters
- Apply same rate limiting as PDF/DOCX (10 exports per hour)
- Verify book ownership (same pattern as existing endpoints)
- Log export access using `chapter_access_service.log_access()` with `access_type="export_epub"`
- Call `export_service.export_book()` with `format="epub"`
- Return `StreamingResponse` with MIME type `application/epub+zip`
- Set `Content-Disposition` header with sanitized filename ending in `.epub`
- Handle errors with appropriate HTTP status codes

Update `get_export_formats()` endpoint:
- Add EPUB format to the `formats` array with:
  - `format: "epub"`
  - `name: "EPUB eBook"`
  - `description: "Electronic publication format - ideal for e-readers and mobile devices"`
  - `mime_type: "application/epub+zip"`
  - `extension: ".epub"`
  - `options: {"include_empty_chapters": "boolean"}`

### 4. Frontend Types

**Update `file:frontend/src/types/export.ts`:**

- Change `ExportFormat` type from `'pdf' | 'docx'` to `'pdf' | 'docx' | 'epub'`

**Update `file:frontend/src/components/export/types.ts`:**

- Change `ExportFormat` type to include `'epub'`

### 5. Frontend API Client

**Extend `file:frontend/src/lib/api/bookClient.ts`:**

Add new `exportEPUB()` method:
- Accept `bookId` and `options?: { includeEmptyChapters?: boolean }` parameters
- Build URLSearchParams with `include_empty_chapters` if provided
- Fetch from `${this.baseUrl}/books/${bookId}/export/epub?${params}`
- Include authentication headers via `getHeaders()`
- Return response as `Blob`
- Handle errors with descriptive messages

### 6. Frontend Export UI Components

**Update `file:frontend/src/components/export/ExportOptionsModal.tsx`:**

Add EPUB option to the format selection RadioGroup:
- Create new RadioGroupItem with `value="epub"` and `id="format-epub"`
- Display "EPUB eBook" as the label
- Show description: "Electronic publication format - optimized for e-readers like Kindle, Kobo, and Apple Books"
- Use appropriate icon (e.g., book icon with different color)
- EPUB format should not show page size options (only `includeEmptyChapters`)

**Update `file:frontend/src/app/dashboard/books/[bookId]/export/page.tsx`:**

Extend the `handleExport()` function:
- Add `else if (selectedFormat === 'epub')` condition
- Call `bookClient.exportEPUB(bookId, { includeEmptyChapters })`
- Handle the returned blob same as PDF/DOCX

Update format icons mapping:
- Add EPUB icon (e.g., '📚' or '📖') in the `formatsWithIcons` mapping

### 7. Frontend Export Helpers

**Update `file:frontend/src/components/export/exportHelpers.ts`:**

- Modify format validation to accept `'epub'` in addition to `'pdf'` and `'docx'`
- Update any format-specific logic to handle EPUB

### 8. Frontend Performance Tracking

**Update `file:frontend/src/lib/loading/timeEstimator.ts`:**

Add EPUB export time estimates:
- Add `'export.epub'` entry to operation profiles with:
  - `base: 8000` (8 seconds base time)
  - `perThousandWords: 1500` (1.5 seconds per 1000 words)
  - `perChapter: 800` (0.8 seconds per chapter)
  - `min: 5000`, `max: 60000`

**Update `file:frontend/src/lib/performance/budgets.ts`:**

Add EPUB export performance budget:
- Add `'export-epub'` entry with:
  - `name: 'export-epub'`
  - `target: 5000`
  - `warningThreshold: 0.8`
  - `description: 'Export book to EPUB format'`
  - `priority: 1`

### 9. Backend Tests

**Update `file:backend/tests/test_services/test_export_service.py`:**

Add EPUB-specific test methods:
- `test_generate_epub()`: Test basic EPUB generation, verify bytes start with `b'PK'` (ZIP signature)
- `test_export_book_epub()`: Test complete book export to EPUB format
- `test_epub_metadata()`: Verify metadata is properly embedded (title, author, etc.)
- `test_epub_toc()`: Verify table of contents structure is correct
- `test_epub_with_nested_chapters()`: Test subchapter handling in EPUB TOC
- Extend `test_export_invalid_format()` to ensure EPUB is recognized as valid

**Update `file:backend/tests/test_api/test_export_endpoints.py`:**

Add EPUB endpoint tests:
- `test_export_epub_success()`: Test successful EPUB export with proper MIME type
- `test_export_epub_with_options()`: Test EPUB export with `include_empty_chapters` option
- Update `test_export_formats_endpoint()` to verify EPUB appears in formats list
- Verify EPUB format has correct metadata (name, extension, MIME type)

### 10. Frontend Tests

**Update `file:frontend/src/components/export/ExportOptionsModal.test.tsx`:**

- Add test case for EPUB format selection
- Verify EPUB option appears in the format list
- Test that EPUB doesn't show page size options (unlike PDF)

**Update `file:frontend/src/__tests__/utils/exportUtils.test.tsx`:**

- Add EPUB format validation tests
- Test EPUB export helper functions

### 11. E2E Tests

**Update `file:frontend/tests/e2e/deployment/02-user-journey.spec.ts`:**

Add EPUB export test:
- Navigate to export page
- Select EPUB format
- Configure options (include empty chapters)
- Trigger export
- Verify download starts with correct filename (`.epub` extension)
- Verify download completes successfully
- Add performance budget check using `PERFORMANCE_BUDGETS.EXPORT_EPUB`

**Update `file:frontend/tests/e2e/page-objects/export.page.ts`:**

- Add EPUB-specific selectors and methods
- Add `selectEpubFormat()` method
- Add `exportAsEpub()` method

### 12. Documentation Updates

**Update user-facing documentation:**

- Update `file:AUTO_AUTHOR_USER_MANUAL.md` to move EPUB from "Future Features" to current features
- Update `file:docs/export-functionality.md` to include detailed EPUB export instructions
- Update `file:AUTO_AUTHOR_GAP_ANALYSIS.md` to mark EPUB export as implemented

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant ExportUI as Export UI<br/>(page.tsx)
    participant BookClient as Book Client<br/>(bookClient.ts)
    participant ExportAPI as Export API<br/>(export.py)
    participant ExportService as Export Service<br/>(export_service.py)
    participant EbookLib as ebooklib

    User->>ExportUI: Select EPUB format
    User->>ExportUI: Configure options
    User->>ExportUI: Click "Export"
    
    ExportUI->>BookClient: exportEPUB(bookId, options)
    BookClient->>ExportAPI: GET /books/{id}/export/epub
    
    ExportAPI->>ExportAPI: Verify ownership
    ExportAPI->>ExportAPI: Log access
    ExportAPI->>ExportService: export_book(format="epub")
    
    ExportService->>ExportService: Flatten chapters
    ExportService->>ExportService: generate_epub()
    ExportService->>EbookLib: Create EpubBook
    ExportService->>EbookLib: Add metadata
    ExportService->>EbookLib: Add chapters
    ExportService->>EbookLib: Generate TOC
    ExportService->>EbookLib: Write EPUB
    
    EbookLib-->>ExportService: EPUB bytes
    ExportService-->>ExportAPI: EPUB bytes
    ExportAPI-->>BookClient: StreamingResponse (EPUB)
    BookClient-->>ExportUI: Blob
    
    ExportUI->>ExportUI: Create download link
    ExportUI->>User: Download EPUB file
```

## Implementation Summary

| Component | Files Modified | New Files | Tests Added |
|-----------|---------------|-----------|-------------|
| Backend Service | `export_service.py` | None | 5 test methods |
| Backend API | `export.py` | None | 3 test methods |
| Backend Dependencies | `requirements.in`, `requirements.txt`, `pyproject.toml` | None | N/A |
| Frontend Types | `export.ts`, `types.ts` | None | N/A |
| Frontend API | `bookClient.ts` | None | N/A |
| Frontend UI | `ExportOptionsModal.tsx`, `page.tsx`, `exportHelpers.ts` | None | 2 test cases |
| Frontend Performance | `timeEstimator.ts`, `budgets.ts` | None | N/A |
| E2E Tests | `02-user-journey.spec.ts`, `export.page.ts` | None | 1 test scenario |
| Documentation | `AUTO_AUTHOR_USER_MANUAL.md`, `export-functionality.md`, `AUTO_AUTHOR_GAP_ANALYSIS.md` | None | N/A |

**Total Estimated Effort:** 8-10 hours

---

Execution Information

Branch: main
Commit: 7bfd621