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