From baa46a8a63063eb106d1f921533f05ad8c57ea0c Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 26 Jan 2026 11:54:53 -0500 Subject: [PATCH] Update documentation to reflect interactive rating system and API changes - Update README.md with interactive rating system details - Document zero-rating behavior in GET /api/ebooks/:id/rating - Add comprehensive rating system documentation section - Update Bruno collection files to reflect new API behavior - Enhance API testing documentation with rating 0 fallback --- README.md | 37 ++++++++++++++++++++++++++----- bruno/README.md | 5 +++-- bruno/ebooks/Get Ebook Rating.bru | 10 +++++++-- 3 files changed, 43 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9e927de..0a53fe0 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ A self-hosted ebook management system built with Go, PostgreSQL, HTMX, and Tailw - **πŸŒ™ Multiple Themes**: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, FrappΓ©, Latte) with user preferences saved to database - **🎨 Theme Persistence**: User theme choices sync between browser and server - **πŸ“– Reading Progress**: User-specific reading progress tracking -- **⭐ User Ratings**: Rate and review ebooks with personalized rating system +- **⭐ Interactive Rating System**: 5-star rating system with interactive dashboard controls and zero-rating fallback - **πŸ“ Multiple Folder Support**: Configure multiple ebook folders per user for comprehensive library management - **πŸ” Enhanced Scanner**: Intelligent ebook discovery with Calibre folder structure support and comprehensive metadata extraction - **πŸ‘€ Real-Time Monitoring**: File system monitoring for automatic ebook detection and updates @@ -161,9 +161,9 @@ The application uses Go HTML templates for server-side rendering with HTMX for d - `PUT /api/ebooks/:id/progress` - Update reading progress ### Ratings (Protected) -- `GET /api/ebooks/:id/rating` - Get user's rating for ebook -- `POST /api/ebooks/:id/rating` - Create or update ebook rating -- `PUT /api/ebooks/:id/rating` - Create or update ebook rating +- `GET /api/ebooks/:id/rating` - Get user's rating for ebook (returns 0 when no rating exists) +- `POST /api/ebooks/:id/rating` - Create or update ebook rating (1-5 stars) +- `PUT /api/ebooks/:id/rating` - Create or update ebook rating (1-5 stars) - `DELETE /api/ebooks/:id/rating` - Delete user's rating - `GET /api/ebooks/:id/ratings` - Get all ratings for ebook @@ -172,6 +172,33 @@ The application uses Go HTML templates for server-side rendering with HTMX for d - `POST /api/scanner/start` - Start real-time monitoring of configured folders - `POST /api/scanner/stop` - Stop real-time folder monitoring +## ⭐ Interactive Rating System + +Bookmann features a fully interactive 5-star rating system integrated directly into the dashboard: + +### Rating Scale +- **1-5 stars**: Standard rating scale for ebooks +- **0 stars**: Automatically shown when no rating exists +- **User-specific**: Each user has their own ratings per ebook + +### Dashboard Integration +- **Visual Rating Display**: Interactive star widgets for each ebook +- **Click-to-Rate**: Simply click on stars to set/update ratings +- **Real-time Updates**: Rating changes reflect immediately without page reload +- **Graceful Fallback**: Shows empty stars (β˜†) for unrated books + +### API Behavior +- **GET /api/ebooks/:id/rating**: Returns rating 0 (HTTP 200) when no rating exists +- **POST/PUT /api/ebooks/:id/rating**: Create or update ratings (1-5) +- **DELETE /api/ebooks/:id/rating**: Remove user's rating +- **pgx v5 Standards**: All database operations use modern pgx error handling + +### Frontend Features +- **HTMX Integration**: Smooth interactions without full page refreshes +- **Responsive Design**: Mobile-friendly rating controls +- **Theme Support**: Rating stars adapt to user's selected theme +- **Error Handling**: Graceful degradation when API calls fail + ## πŸ“ Enhanced Ebook Scanner Bookmann includes an intelligent ebook scanner with full Calibre integration and smart folder structure detection. @@ -312,7 +339,7 @@ Use the included Bruno collection in the `bruno/` directory for testing the API: - **Multiple Folder Support**: Users can configure multiple ebook directories with per-user folder management - **Real-Time Monitoring**: File system watching for automatic ebook updates with dynamic subfolder detection - **Scan Settings**: User-configurable scan frequency and auto-scan options -- **Rating System**: User-specific ebook ratings with full CRUD operations +- **Interactive Rating System**: 5-star dashboard controls with click-to-rate functionality, zero-rating fallback, and full CRUD operations ### Frontend Redesign - **Beautiful Homepage**: Hero section with features showcase and modern design diff --git a/bruno/README.md b/bruno/README.md index f68840f..888d48b 100644 --- a/bruno/README.md +++ b/bruno/README.md @@ -29,7 +29,7 @@ This directory contains Bruno collection for testing the Bookmann API with compr - **Update Reading Progress**: PUT /api/ebooks/:id/progress - Update progress ### Ratings (Protected - JWT Required) -- **Get Ebook Rating**: GET /api/ebooks/:id/rating - User's rating for ebook +- **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 @@ -47,7 +47,8 @@ Each request includes: - **Authentication Flow**: Register β†’ Login β†’ Use Bearer token for all other requests - **JWT Tokens**: Valid for 24 hours, include in `Authorization: Bearer ` header -- **User Isolation**: Progress and data are user-specific +- **User Isolation**: Progress, ratings, and data are user-specific +- **Rating Behavior**: Get rating returns 0 when no rating exists (instead of 404) - **Variables**: Update `ebook_id` for testing specific ebooks - **Security**: Passwords hashed with bcrypt, unique email/username constraints - **JSON**: All requests/responses use JSON format \ No newline at end of file diff --git a/bruno/ebooks/Get Ebook Rating.bru b/bruno/ebooks/Get Ebook Rating.bru index 0bf59e1..5f3f0cd 100644 --- a/bruno/ebooks/Get Ebook Rating.bru +++ b/bruno/ebooks/Get Ebook Rating.bru @@ -25,7 +25,7 @@ docs { **Path Parameters:** - `id` (string): Ebook UUID - **Response:** + **Response when rating exists:** - `id` (string): Rating UUID - `ebook_id` (string): Ebook UUID - `user_id` (string): User UUID @@ -33,7 +33,13 @@ docs { - `created_at` (string): Creation timestamp - `updated_at` (string): Last update timestamp + **Response when no rating exists:** + - `ebook_id` (string): Ebook UUID + - `user_id` (string): User UUID + - `rating` (number): Always 0 (indicates no rating) + **Error Responses:** - 401: Invalid authentication - - 404: Rating not found + + **Note:** This endpoint returns HTTP 200 with rating 0 when no rating exists, instead of HTTP 404. } \ No newline at end of file