bookhoard/bruno/README.md

Bruno API Tests for Bookmann

This directory contains Bruno collection for testing the Bookmann 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 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)

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 with user_id parameter
• Register Admin User: POST /api/auth/register - Create admin account (requires existing admin authentication)

Collection Organization

bruno/user/
├── auth/                    # Authentication requests
│   ├── Login User.bru      # POST /api/auth/login
│   └── Register User.bru   # POST /api/auth/register (with restrictions)
├── admin/                   # Admin-only management
│   ├── List Users.bru         # GET /api/auth/users (admin only)
│   ├── Delete Account.bru       # DELETE /api/auth/account (admin override)
│   └── Register Admin User.bru # POST /api/auth/register (admin creation)
└── profile/                  # Profile management
    ├── Get Profile.bru         # GET /api/auth/profile
    ├── Update Profile.bru       # PUT /api/auth/profile
    ├── Update Email.bru         # PUT /api/auth/email
    ├── Update Password.bru       # PUT /api/auth/password
    ├── Update Theme.bru         # PUT /api/auth/theme
    └── Update Username.bru       # PUT /api/auth/username

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

Admin Deletion

• Self-Deletion: Users can delete their own accounts
• Admin Override: Admins can delete any user account via ?user_id={uuid} parameter
• Last Admin Protection: Cannot delete the last admin account in the system

User Management (Protected)

• Delete Account: DELETE /api/auth/account - Delete own account (self) or admin deletes other accounts with user_id parameter (admin only)

Folders (Admin Only)

• Add Ebook Folder: POST /api/auth/ebook-folders - Add folder for scanning (admin only)
• Get Ebook Folders: GET /api/auth/ebook-folders - List configured folders (admin only)
• Delete Ebook Folder: DELETE /api/auth/ebook-folders - Remove folder (admin only)

Ebooks (Mixed Access)

• List Ebooks: GET /api/ebooks - Paginated ebook list (all authenticated users)
• Get Ebook: GET /api/ebooks/:id - Single ebook details (all authenticated users)
• Create Ebook: POST /api/ebooks - Add new ebook (admin only)
• Update Ebook: PUT /api/ebooks/:id - Modify ebook metadata (admin only)
• Delete Ebook: DELETE /api/ebooks/:id - Remove ebook (admin only)

Scanner (Admin Only)

• Scan Ebooks: POST /api/scanner/scan - Scan configured folders (admin only)
• Start Scanner: POST /api/scanner/start - Start real-time monitoring (admin only)
• Stop Scanner: POST /api/scanner/stop - Stop monitoring (admin only)

Reading Progress (All Users)

• Get Reading Progress: GET /api/ebooks/:id/progress - User's progress
• Update Reading Progress: PUT /api/ebooks/:id/progress - Update progress

Ratings (All Users)

• Get Ebook Rating: GET /api/ebooks/:id/rating - User's rating for ebook (returns 0 if unrated)
• Create/Update Rating: POST /api/ebooks/:id/rating - Rate ebook (1-5 stars)
• Delete Rating: DELETE /api/ebooks/:id/rating - Remove user's rating
• Get All Ratings: GET /api/ebooks/:id/ratings - All ratings for ebook

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
• JWT Tokens: Valid for 24 hours, include in Authorization: Bearer <token> header
• Role System: Two roles - 'admin' and 'user'. Admins can manage folders and ebooks, users can view/rate/track progress
• Shared Library: All users can view the complete ebook collection, but only admins can modify it
• User Isolation: Progress, ratings, and profile data are user-specific
• Rating Behavior: Get rating returns 0 when no rating exists (instead of 404)
• Admin Setup: First admin must be created by updating user role in database: UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';
• Variables: Update ebook_id for testing specific ebooks
• Security: Passwords hashed with bcrypt, unique email/username constraints, role-based access control
• JSON: All requests/responses use JSON format