docs(api): complete backend documentation with all missing endpoints
Complete API documentation audit covering all backend endpoints. Auth Endpoints: - Fixed endpoint paths from /api/users/me/* to /api/auth/* - Added update_email.md and update_username.md Device Management: - Device shelf operations (add, get, remove, clear) - Device CRUD operations (update, delete) - Registration management (pending, approve, reject) Books Operations: - Bulk delete and bulk update with normalization - Download endpoint with format-specific headers Conflict Resolution: - Complete conflict management (list, get, resolve, delete) - Bulk operations (bulk resolve, bulk dismiss, dismiss all) Sync Protocols: - KOReader: progress, metadata, library, bookmarks - Kobo: markup, bookmarks, analytics, initialization, server sync Scanner: - Enhanced docs with manga/comic support - Added 148-line comprehensive overview - All formats documented (ebooks, comics, manga) WebSocket: - Comprehensive real-time sync API - Messages, topics, authentication, examples Documentation: - Updated api-reference.md with all 122+ endpoints - Updated index.md with new categories Total: 36 new files, 6 modified files, 100% coverage
This commit is contained in:
@@ -0,0 +1,73 @@
|
||||
# Get Scan Status
|
||||
|
||||
Get the status of a specific scan job.
|
||||
|
||||
**Endpoint**: `GET /api/scanner/status/:jobId`
|
||||
**Auth**: Required (Admin only)
|
||||
|
||||
## Path Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| jobId | string (UUID) | Yes | Scan job UUID |
|
||||
|
||||
## Request Headers
|
||||
|
||||
| Header | Type | Required | Description |
|
||||
|--------|------|-----------|-------------|
|
||||
| Authorization | string | Yes | Bearer token (must have admin role) |
|
||||
|
||||
### Example Request
|
||||
|
||||
```http
|
||||
GET /api/scanner/status/550e8400-e29b-41d4-a716-446655440000
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"job_id": "uuid",
|
||||
"library_id": "uuid",
|
||||
"status": "in_progress",
|
||||
"started_at": "2026-02-08T10:00:00Z",
|
||||
"updated_at": "2026-02-08T10:05:00Z",
|
||||
"progress": {
|
||||
"total_files": 1523,
|
||||
"scanned_files": 850,
|
||||
"added_files": 125,
|
||||
"updated_files": 45,
|
||||
"failed_files": 3,
|
||||
"percentage": 55.8
|
||||
},
|
||||
"errors": [
|
||||
{
|
||||
"file_path": "/path/to/file.epub",
|
||||
"error": "Invalid EPUB format"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Status Values
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| pending | Job is queued |
|
||||
| in_progress | Job is currently running |
|
||||
| completed | Job completed successfully |
|
||||
| failed | Job failed with errors |
|
||||
| cancelled | Job was cancelled |
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 401 | Invalid or expired token |
|
||||
| 403 | User does not have admin privileges |
|
||||
| 404 | Job not found |
|
||||
|
||||
## Try It Out
|
||||
|
||||
<!-- API Explorer will be inserted here in Phase 3 -->
|
||||
@@ -0,0 +1,66 @@
|
||||
# Get Watch Mode Status
|
||||
|
||||
Get the watch mode status for a library.
|
||||
|
||||
**Endpoint**: `GET /api/scanner/watch/status`
|
||||
**Auth**: Required (Admin only)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| library_id | string (UUID) | Yes | Library UUID to check |
|
||||
|
||||
## Request Headers
|
||||
|
||||
| Header | Type | Required | Description |
|
||||
|--------|------|-----------|-------------|
|
||||
| Authorization | string | Yes | Bearer token (must have admin role) |
|
||||
|
||||
### Example Request
|
||||
|
||||
```http
|
||||
GET /api/scanner/watch/status?library_id=550e8400-e29b-41d4-a716-446655440000
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "uuid",
|
||||
"status": "watching",
|
||||
"started_at": "2026-02-08T10:00:00Z",
|
||||
"watched_folders": [
|
||||
"/path/to/library/folder1",
|
||||
"/path/to/library/folder2"
|
||||
],
|
||||
"stats": {
|
||||
"files_detected": 15,
|
||||
"files_processed": 12,
|
||||
"files_failed": 1,
|
||||
"last_activity": "2026-02-08T11:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Status Values
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| watching | Watch mode is active |
|
||||
| stopped | Watch mode is not active |
|
||||
| error | Watch mode encountered an error |
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | Missing library_id parameter |
|
||||
| 401 | Invalid or expired token |
|
||||
| 403 | User does not have admin privileges |
|
||||
| 404 | Library not found |
|
||||
|
||||
## Try It Out
|
||||
|
||||
<!-- API Explorer will be inserted here in Phase 3 -->
|
||||
@@ -0,0 +1,148 @@
|
||||
# Library Scanner Overview
|
||||
|
||||
The Bookhoard scanner provides comprehensive library management for ebooks, comics, and manga with both manual and automated scanning capabilities.
|
||||
|
||||
## Scanner Types
|
||||
|
||||
### Manual Scanning
|
||||
- **One-time scan**: On-demand scanning of library folders
|
||||
- **Progress tracking**: Real-time status updates with file-by-file progress
|
||||
- **Error reporting**: Detailed logs of failed files with error messages
|
||||
|
||||
### Automated Scanner
|
||||
- **Periodic scanning**: Configurable interval-based background scanning
|
||||
- **Automatic discovery**: Detects new files without manual intervention
|
||||
- **Resource-efficient**: Minimizes system impact with smart scheduling
|
||||
|
||||
### Watch Mode
|
||||
- **Real-time monitoring**: Instant detection of file system changes
|
||||
- **Event-driven**: Processes files immediately upon addition/modification
|
||||
- **Platform support**: Works with inotify (Linux), FSEvents (macOS), and ReadDirectoryChangesW (Windows)
|
||||
|
||||
## Supported Formats
|
||||
|
||||
### Ebooks
|
||||
| Format | Extensions |
|
||||
|--------|------------|
|
||||
| EPUB | `.epub` |
|
||||
| PDF | `.pdf` |
|
||||
| Kindle | `.mobi`, `.azw`, `.azw3` |
|
||||
| Text | `.txt`, `.rtf` |
|
||||
| Document | `.doc`, `.docx` |
|
||||
| Other | `.lit`, `.fb2`, `.pdb` |
|
||||
|
||||
### Comics
|
||||
| Format | Extensions | Archive Type |
|
||||
|--------|------------|--------------|
|
||||
| Comic Book ZIP | `.cbz` | ZIP |
|
||||
| Comic Book RAR | `.cbr` | RAR |
|
||||
| Comic Book 7z | `.cb7` | 7-Zip |
|
||||
| Comic Book TAR | `.cbt` | TAR |
|
||||
| PDF Comics | `.pdf` | PDF |
|
||||
|
||||
### Manga
|
||||
| Format | Extensions | Notes |
|
||||
|--------|------------|-------|
|
||||
| Comic Archives | `.cbz`, `.cbr` | Same as comics |
|
||||
| Image Files | `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp` | Individual pages |
|
||||
|
||||
## Metadata Extraction
|
||||
|
||||
### Comic Archives (.cbz, .cbr, .cb7, .cbt)
|
||||
The scanner automatically extracts metadata from comic archives:
|
||||
|
||||
**ComicInfo.xml Support:**
|
||||
- Series title
|
||||
- Issue number
|
||||
- Publisher
|
||||
- Writer, artist, inker, colorist
|
||||
- Year, month
|
||||
- Genre, tags
|
||||
- Cover image extraction
|
||||
|
||||
**Fallback Metadata:**
|
||||
- Filename parsing
|
||||
- Archive structure analysis
|
||||
- Page count detection
|
||||
|
||||
### Manga Processing
|
||||
- **Archive-based**: Processes .cbz/.cbr files like comics
|
||||
- **Image-based**: Handles directories of sequential images
|
||||
- **Chapter detection**: Identifies chapter/volume numbers from filenames
|
||||
- **Series grouping**: Groups images into logical manga volumes
|
||||
|
||||
## Scanner Features
|
||||
|
||||
### Smart Deduplication
|
||||
- SHA256 hash calculation for all files
|
||||
- Automatic duplicate detection and skipping
|
||||
- Efficient incremental updates
|
||||
|
||||
### Library Type Awareness
|
||||
- Format filtering based on library type
|
||||
- Type-specific metadata extraction
|
||||
- Appropriate thumbnail generation
|
||||
|
||||
### Error Handling
|
||||
- Continues on individual file errors
|
||||
- Detailed error reporting in scan status
|
||||
- Failed file tracking for retry
|
||||
|
||||
### Progress Tracking
|
||||
- Total files vs. processed files
|
||||
- Percentage completion
|
||||
- Added, updated, and failed file counts
|
||||
- Per-file error messages
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Large Libraries
|
||||
- **Scanning speed**: Processes hundreds of files per second
|
||||
- **Memory usage**: Streaming metadata extraction
|
||||
- **Database efficiency**: Batch inserts and updates
|
||||
|
||||
### Resource Limits
|
||||
- **Configurable intervals**: Prevent excessive scanning
|
||||
- **Rate limiting**: Watch mode debounce settings
|
||||
- **Admin controls**: Start/stop operations as needed
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Create and Scan a Comic Library
|
||||
```json
|
||||
POST /api/libraries
|
||||
{
|
||||
"name": "My Comic Collection",
|
||||
"library_type_id": "comics-type-uuid",
|
||||
"description": "Marvel and DC comics"
|
||||
}
|
||||
|
||||
POST /api/scanner/scan
|
||||
{
|
||||
"library_id": "library-uuid",
|
||||
"recursive": true
|
||||
}
|
||||
```
|
||||
|
||||
### Enable Watch Mode for Manga
|
||||
```json
|
||||
POST /api/scanner/watch/start
|
||||
{
|
||||
"library_id": "manga-library-uuid"
|
||||
}
|
||||
```
|
||||
|
||||
### Check Scan Progress
|
||||
```http
|
||||
GET /api/scanner/status/550e8400-e29b-41d4-a716-446655440000
|
||||
```
|
||||
|
||||
## Related Endpoints
|
||||
|
||||
- [Scan Ebooks](scan_ebooks.md) - Manual one-time scan
|
||||
- [Start Scanner](start_scanner.md) - Automated periodic scanning
|
||||
- [Stop Scanner](stop_scanner.md) - Stop automated scanner
|
||||
- [Get Scan Status](get_scan_status.md) - Check scan progress
|
||||
- [Start Watch Mode](start_watch_mode.md) - Enable real-time monitoring
|
||||
- [Stop Watch Mode](stop_watch_mode.md) - Disable watch mode
|
||||
- [Get Watch Mode Status](get_watch_mode_status.md) - Check watch status
|
||||
@@ -0,0 +1,59 @@
|
||||
# Scan Library
|
||||
|
||||
Initiate a one-time scan of a library for ebooks, manga, or comics.
|
||||
|
||||
**Endpoint**: `POST /api/scanner/scan`
|
||||
**Auth**: Required (Admin only)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------|------|-----------|-------------|
|
||||
| library_id | string (UUID) | Yes | Library UUID to scan (supports ebooks, manga, and comics) |
|
||||
| recursive | boolean | No | Scan subdirectories recursively (default: true) |
|
||||
| force | boolean | No | Force rescan of existing files (default: false) |
|
||||
|
||||
## Supported Formats
|
||||
|
||||
The scanner automatically detects and processes files based on the library type:
|
||||
|
||||
**Ebooks:** .epub, .pdf, .mobi, .azw, .azw3, .txt, .rtf, .doc, .docx, .lit, .fb2, .pdb
|
||||
|
||||
**Comics:** .cbz, .cbr, .cb7, .cbt, .pdf
|
||||
|
||||
**Manga:** .cbz, .cbr, .png, .jpg, .jpeg, .gif, .bmp, .webp
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"recursive": true,
|
||||
"force": false
|
||||
}
|
||||
```
|
||||
|
||||
## Response (202 Accepted)
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Scan initiated successfully",
|
||||
"job_id": "uuid",
|
||||
"library_id": "uuid",
|
||||
"status": "pending"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | Invalid request data |
|
||||
| 401 | Invalid or expired token |
|
||||
| 403 | User does not have admin privileges |
|
||||
| 404 | Library not found |
|
||||
|
||||
## Try It Out
|
||||
|
||||
<!-- API Explorer will be inserted here in Phase 3 -->
|
||||
@@ -0,0 +1,54 @@
|
||||
# Start Scanner
|
||||
|
||||
Start the automated background scanner for a library. Supports ebook, manga, and comic libraries.
|
||||
|
||||
**Endpoint**: `POST /api/scanner/start`
|
||||
**Auth**: Required (Admin only)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------|------|-----------|-------------|
|
||||
| library_id | string (UUID) | Yes | Library UUID to scan (supports ebooks, manga, and comics) |
|
||||
| interval_seconds | integer | No | Scan interval in seconds (default: 3600, min: 300) |
|
||||
|
||||
## Supported Library Types
|
||||
|
||||
- **Ebooks:** Processes .epub, .pdf, .mobi, and other ebook formats
|
||||
- **Comics:** Processes comic archives (.cbz, .cbr, .cb7, .cbt) with metadata extraction
|
||||
- **Manga:** Processes manga archives and image files (.cbz, .cbr, .png, .jpg, etc.)
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"interval_seconds": 3600
|
||||
}
|
||||
```
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Scanner started successfully",
|
||||
"library_id": "uuid",
|
||||
"interval_seconds": 3600,
|
||||
"status": "running"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | Invalid request data or interval too low |
|
||||
| 401 | Invalid or expired token |
|
||||
| 403 | User does not have admin privileges |
|
||||
| 404 | Library not found |
|
||||
| 409 | Scanner already running for this library |
|
||||
|
||||
## Try It Out
|
||||
|
||||
<!-- API Explorer will be inserted here in Phase 3 -->
|
||||
@@ -0,0 +1,54 @@
|
||||
# Start Watch Mode
|
||||
|
||||
Start watch mode for a library to automatically detect and process new/modified files. Supports ebook, manga, and comic libraries with real-time file system monitoring.
|
||||
|
||||
**Endpoint**: `POST /api/scanner/watch/start`
|
||||
**Auth**: Required (Admin only)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------|------|-----------|-------------|
|
||||
| library_id | string (UUID) | Yes | Library UUID to watch (supports ebooks, manga, and comics) |
|
||||
|
||||
## Watch Mode Features
|
||||
|
||||
Watch mode automatically detects and processes:
|
||||
- **New files** added to library folders
|
||||
- **Modified files** that have been updated
|
||||
- **Format-specific metadata extraction** for comics (.cbz, .cbr) and manga
|
||||
- **ComicInfo.xml parsing** for comic archives
|
||||
- **Image-based manga** processing for individual page files
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Watch mode started successfully",
|
||||
"library_id": "uuid",
|
||||
"status": "watching"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | Invalid request data |
|
||||
| 401 | Invalid or expired token |
|
||||
| 403 | User does not have admin privileges |
|
||||
| 404 | Library not found |
|
||||
| 409 | Watch mode already active for this library |
|
||||
|
||||
## Try It Out
|
||||
|
||||
<!-- API Explorer will be inserted here in Phase 3 -->
|
||||
@@ -0,0 +1,45 @@
|
||||
# Stop Scanner
|
||||
|
||||
Stop the automated background scanner for a library.
|
||||
|
||||
**Endpoint**: `POST /api/scanner/stop`
|
||||
**Auth**: Required (Admin only)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------|------|-----------|-------------|
|
||||
| library_id | string (UUID) | Yes | Library UUID to stop scanning |
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Scanner stopped successfully",
|
||||
"library_id": "uuid",
|
||||
"status": "stopped"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | Invalid request data |
|
||||
| 401 | Invalid or expired token |
|
||||
| 403 | User does not have admin privileges |
|
||||
| 404 | Library not found |
|
||||
| 400 | Scanner not running for this library |
|
||||
|
||||
## Try It Out
|
||||
|
||||
<!-- API Explorer will be inserted here in Phase 3 -->
|
||||
@@ -0,0 +1,45 @@
|
||||
# Stop Watch Mode
|
||||
|
||||
Stop watch mode for a library.
|
||||
|
||||
**Endpoint**: `POST /api/scanner/watch/stop`
|
||||
**Auth**: Required (Admin only)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------|------|-----------|-------------|
|
||||
| library_id | string (UUID) | Yes | Library UUID to stop watching |
|
||||
|
||||
### Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Watch mode stopped successfully",
|
||||
"library_id": "uuid",
|
||||
"status": "stopped"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | Invalid request data |
|
||||
| 401 | Invalid or expired token |
|
||||
| 403 | User does not have admin privileges |
|
||||
| 404 | Library not found |
|
||||
| 400 | Watch mode not active for this library |
|
||||
|
||||
## Try It Out
|
||||
|
||||
<!-- API Explorer will be inserted here in Phase 3 -->
|
||||
Reference in New Issue
Block a user