opencollection: 1.0.0

info:
  name: Bookhoard
config:
  proxy:
    inherit: true
    config:
      protocol: http
      hostname: ""
      port: ""
      auth:
        username: ""
        password: ""
      bypassProxy: ""

request:
  auth:
    type: bearer
    token: "{{token}}"

docs:
  content: |-
    # Bruno OpenCollection YAML API Tests for Bookhoard
    This directory contains Bruno OpenCollection YAML format tests for testing the Bookhoard API with comprehensive REST documentation.
     Setup
    1. Install Bruno: https://www.usebruno.com/
    2. Open Bruno and import this collection folder
    3. Select the "localhost" environment
    4. Start the application with `podman-compose up --build` or `docker-compose up --build`
    5. Register/Login first, then use Bearer token for protected endpoints
     Available Tests
     Authentication (Public & Private)
    - **Register User**: POST /api/auth/register - Create new account with role-based restrictions
    - **Login User**: POST /api/auth/login - Authenticate (email or username)
    - **Refresh Token**: POST /api/auth/refresh - Get new access token
    - **Logout**: POST /api/auth/logout - Invalidate refresh token
     User Profile Management
    - **Get Profile**: GET /api/auth/profile - Get current user info
    - **Update Profile**: PUT /api/auth/profile - Update first_name, last_name
    - **Update Email**: PUT /api/auth/email - Update email address
    - **Update Username**: PUT /api/auth/username - Update username
    - **Update Password**: PUT /api/auth/password - Update password
    - **Update Theme**: PUT /api/auth/theme - Update theme preference
     Admin User Management
    - **List Users**: GET /api/auth/users - Get all users with complete info (admin only)
    - **Delete Account**: DELETE /api/auth/account - Delete own account or admin deletes other accounts
     Libraries (Admin Only)
    - **Create Library**: POST /api/libraries - Create new library (Ebooks, Comics, Manga)
    - **Get Libraries**: GET /api/libraries - List all libraries (admin)
    - **Get Library**: GET /api/libraries/:id - Get library details
    - **Update Library**: PUT /api/libraries/:id - Update library settings
    - **Delete Library**: DELETE /api/libraries/:id - Remove library
    - **Add Library Folder**: POST /api/libraries/:id/folders - Add scanning folder
    - **Get Library Folders**: GET /api/libraries/:id/folders - List folders
    - **Delete Library Folder**: DELETE /api/libraries/:id/folders/:folder_id - Remove folder
    - **Get Library Stats**: GET /api/libraries/:id/stats - Library statistics
    - **Get Library Types**: GET /api/libraries/types - Available library types
     Media Items (Mixed Access)
    - **List Media Items**: GET /api/media-items - Paginated list (filter/sort by library, author, series, etc.)
    - **Get Media Item**: GET /api/media-items/:id - Single item details (all users)
    - **Create Media Item**: POST /api/media-items - Add new item (admin only)
    - **Update Media Item**: PUT /api/media-items/:id - Modify metadata (admin only)
    - **Delete Media Item**: DELETE /api/media-items/:id - Remove item (admin only)
    - **Filter Media Items**: POST /api/media-items/filter - Advanced filtering
    - **EPUB Download**: GET /api/media-items/:id/download - Download EPUB file
    - **Cover Image**: GET /api/media-items/:id/cover - Get cover image
     Reading Progress (All Users)
    - **Get Progress**: GET /api/progress/:media_id - User's reading progress for media item
    - **Update Progress**: PUT /api/progress/:media_id - Update reading progress
    - **Get Device Progress**: GET /api/progress/device/:device_id - Progress by device
     Universal Progress (All Users)
    - **Get Universal Progress**: GET /api/universal-progress/:sha256 - Get progress by book hash
    - **Update Universal Progress**: PUT /api/universal-progress - Update universal progress
     Notes (All Users)
    - **Get Notes**: GET /api/notes/:media_id - Get notes for media item
    - **Create Note**: POST /api/notes - Add new note
    - **Update Note**: PUT /api/notes/:id - Update note content
    - **Delete Note**: DELETE /api/notes/:id - Remove note
     Highlights (All Users)
    - **Get Highlights**: GET /api/highlights/:media_id - Get highlights for media item
    - **Create Highlight**: POST /api/highlights - Add new highlight
    - **Update Highlight**: PUT /api/highlights/:id - Update highlight
    - **Delete Highlight**: DELETE /api/highlights/:id - Remove highlight
     Ratings (All Users)
    - **Get Rating**: GET /api/ratings/:media_id - User's rating (returns 0 if unrated)
    - **Create/Update Rating**: POST /api/ratings - Rate media item (1-5 stars, half-star precision)
    - **Delete Rating**: DELETE /api/ratings/:media_id - Remove rating
     Collections (All Users)
    - **List Collections**: GET /api/collections - Get user's collections
    - **Get Collection**: GET /api/collections/:id - Collection details with media items
    - **Create Collection**: POST /api/collections - Create new collection
    - **Update Collection**: PUT /api/collections/:id - Update collection
    - **Delete Collection**: DELETE /api/collections/:id - Remove collection
    - **Add Auto-Assign Rule**: POST /api/collections/:id/rules - Add automatic rule
    - **Remove Auto-Assign Rule**: DELETE /api/collections/:id/rules/:rule_id - Remove rule
    - **Test Rule**: POST /api/collections/:id/rules/test - Preview rule matches
    - **Bulk Assign**: POST /api/collections/:id/assign - Manually add media items
     Device Management (All Users)
    - **Register Device**: POST /api/devices/register - Register new device
    - **List Devices**: GET /api/devices - Get user's devices
    - **Get Device**: GET /api/devices/:id - Device details
    - **Delete Device**: DELETE /api/devices/:id - Unregister device
    - **Sync Device**: POST /api/devices/:id/sync - Trigger device sync
     Sync Protocols (Device Integration)
    - **KOReader Sync**: POST /api/sync/koreader - KOReader progress/notes/highlights sync
    - **Kobo Sync**: POST /api/sync/kobo - Kobo progress/notes/highlights sync
     Scanner (Admin Only)
    - **Scan Libraries**: POST /api/scanner/scan - Scan library folders
    - **Start Scanner**: POST /api/scanner/start - Start real-time monitoring
    - **Stop Scanner**: POST /api/scanner/stop - Stop monitoring
    - **Get Scan Settings**: GET /api/scanner/settings - Scan configuration
     Analytics (Admin Only)
    - **Get Analytics**: GET /api/analytics - Usage statistics and metrics
     Book Matching (All Users)
    - **Search Books**: GET /api/book-matching/search - Search by ISBN, title, author
    - **Link Book**: POST /api/book-matching/link - Link media item to external database
     OPDS (All Users)
    - **OPDS Feeds**: GET /opds/* - OPDS catalog for e-reader integration
    - **OPDS Acquisition**: GET /opds/acquisition/* - Download media items
     WebSocket (Real-time)
    - **WebSocket**: WS /api/ws - Real-time sync events (progress, notes, highlights)
     Collection Organization
    bruno/
    ├── user/                     # User authentication and profile
    │   ├── auth/                 # Login, register, refresh
    │   ├── profile/              # Profile management
    │   └── admin/                # User administration (admin only)
    ├── library/                  # Library management
    │   ├── Create/Update/Delete Libraries
    │   ├── Library Folders
    │   ├── Library Stats
    │   └── Scan Settings
    ├── media-items/              # Media item operations
    │   ├── List/Get/Create/Update/Delete
    │   ├── Filter and Sort
    │   ├── Download EPUB
    │   ├── Cover Images
    │   └── Ratings
    ├── progress/                 # Reading progress tracking
    ├── universal-progress/       # Cross-device universal progress
    ├── notes/                    # User notes
    ├── highlights/               # Book highlights
    ├── collections/              # Smart collections
    ├── devices/                  # Device registration
    ├── sync-koreader/            # KOReader sync protocol
    ├── sync-kobo/                # Kobo sync protocol
    ├── scanner/                  # Library scanning
    ├── analytics/                # Usage statistics
    ├── books/                    # Book matching/linking
    ├── kobo/                     # Kobo-specific operations
    ├── koreader/                 # KOReader-specific operations
    ├── opds/                     # OPDS catalog feeds
    └── admin/                    # Admin operations
    ## Security Features
    ### Registration Restrictions
    - **First User**: Automatically gets admin role regardless of request
    - **Existing Admins**: Only authenticated admins can create new admin accounts
    - **Regular Users**: Anyone can create regular user accounts
    - **Unauthenticated**: Can only create first admin, not subsequent admins
    ### User Management
    - **Self-Deletion**: Users can delete their own accounts
    - **Admin Override**: Admins can delete any user account
    - **Last Admin Protection**: Cannot delete the last admin account in the system
    ### Role System
    - **Admin**: Full access - manage libraries, media items, users, scanner
    - **User**: Read access - view media items, create collections, track progress, rate, annotate
    ### Device Authentication
    - **No Passwords**: Devices use QR code registration and access tokens
    - **User Approval**: Device registration requires user approval via web interface
    ### JWT Tokens
    - **Access Token**: Valid for 1 hour, sent via Bearer header
    - **Refresh Token**: Valid for 7 days, used to get new access tokens
    ### Rate Limiting
    - **Auth Endpoints**: 10 requests/minute per IP
    ### Data Isolation
    - **Progress, Notes, Highlights, Ratings**: User-specific
    - **Collections**: User-specific (admins see all users' collections)
    - **Devices**: User-specific
    ## Documentation Features
    Each request includes:
    - **Detailed descriptions** of functionality
    - **Parameter specifications** (required/optional, types)
    - **Request/Response examples**
    - **Error response codes** and meanings
    - **Authentication requirements**
    ## Notes
    - **Authentication Flow**: Register → Login → Use Bearer token for all other requests
    - **Media Items vs Books**: The API uses "media items" (supports ebooks, comics, manga)
    - **Library System**: Organized by libraries (Ebooks, Comics, Manga) with scanning folders
    - **Universal Progress**: Cross-device sync using SHA-256 book hashes
    - **Smart Collections**: Auto-assign rules based on genre, author, series, tags, etc.
    - **OPDS Support**: Wireless book delivery to e-readers (Kobo, KOReader)
    - **Device Protocols**: Native sync for KOReader and Kobo devices
    - **Rating System**: Half-star precision (1-10 scale internally, displayed as 1-5 stars)
    - **Admin Setup**: First admin must be created by updating user role in database
    - **Variables**: Update collection variables for testing (media_id, library_id, device_id, etc.)
    - **Security**: Passwords hashed with bcrypt, unique email/username constraints, role-based access control
    - **JSON**: All requests/responses use JSON format
    - **WebSocket**: Real-time events for sync updates across devices
  type: text/markdown
bundled: false
extensions: {}
