BookStore REST API (1.0.0)

Creates a new customer account in the BookStore database using the supplied personal details, contact numbers, date of birth, and physical delivery address.

Upon account creation:

1. A user record is persisted in MongoDB with role: "user", isEmailVerified: false, isActive: true, and an empty cart and favourites list.
2. A 6-digit numeric verification OTP is generated with a 30-second expiration window (verificationTokenExpiry).
3. An HTML verification email is dispatched via Nodemailer to the user's email address (or development mailbox).
4. If the email fails to deliver, the newly created user record is rolled back and deleted from the database.
5. The client must submit the received OTP to /auth/verifyOtp within 30 seconds to verify their email and obtain an access token.

Rate limit: 5 requests per minute.

Authenticates an existing user account using email and password credentials.

Authentication flow:

1. Express-validator checks that email and password fields are present and well-formed.
2. User is looked up in MongoDB by email address.
3. check if user account is deactivated, if it is then return error message
4. The submitted plain password is verified against the bcrypt password hash.
5. A JSON Web Token (JWT) signed with JWT_SECRET_KEY and configured expiration (JWT_EXPIRES) is generated containing the user ID payload { id: userId }.
6. The JWT token and complete user profile are returned to the client.

Client requests to protected endpoints must supply this token in the header: Authorization: Bearer <JWT_TOKEN>

Rate limit: 5 requests per minute.

Verifies the 6-digit one-time password (OTP) sent to the user's email during registration.

Verification logic:

1. Client provides email and the 6-digit otp.
2. Server checks if the user account exists in MongoDB.
3. Verifies whether the account is already verified (isEmailVerified === true).
4. Checks whether the OTP has expired (Date.now() > verificationTokenExpiry).
5. Validates the submitted OTP against the stored emailVerifiedToken.
6. Upon successful verification:
   • isEmailVerified is updated to true.
   • emailVerifiedToken and verificationTokenExpiry are cleared.
   • A signed JWT access token is minted and returned so the user can immediately interact with protected endpoints.

Rate limit: 5 requests per minute.

Generates and sends a new 6-digit verification OTP to the user's registered email address.

Endpoint rules:

1. The account must exist in the database.
2. If the user's email is already verified (isEmailVerified === true), resending is rejected with 400.
3. A fresh OTP is generated with a new 30-second expiry timestamp.
4. An HTML email with the new OTP is dispatched via Nodemailer.

Rate limit: 5 requests per minute.

Generates a secure password reset token and emails a reset link to the user.

Security & controller requirements:

1. Protected Route: Requires a valid JWT Bearer token in the Authorization header (protect middleware).
2. The authenticated user must have a verified email address (isEmailVerified === true).
3. The email to reset is provided in the request body.
4. A 32-byte cryptographically secure random token is generated and SHA-256 hashed into passwordResetToken on the user record.
5. The reset token has a 30-second expiry (passwordExpires = Date.now() + 30 * 1000).
6. An email containing the password reset link ${protocol}://${host}/auth/resetPassword/${resetToken} is sent to the customer.

Rate limit: 5 requests per minute.

Changes the user's password using the unhashed password reset token received via email.

Flow & controller requirements:

1. Protected Route: Requires a valid JWT Bearer token in the Authorization header (protect middleware).
2. The reset token is supplied as a URL path parameter :token.
3. The server hashes :token with SHA-256 and searches for a user where passwordResetToken matches and passwordExpires > Date.now().
4. If the token is invalid or expired (30-second lifespan), an error is returned.
5. The new password is set, passwordResetToken and passwordExpires are cleared to undefined, and the user document is saved (which triggers bcrypt hashing via Mongoose pre('save')).

Rate limit: 5 requests per minute.

Retrieves aggregated key performance statistics for the administrator dashboard.

The dashboard aggregates:

• Total revenue from non-cancelled orders
• Total count of orders (all statuses)
• Total books Ordered in system
• Total sales and order count for the current month
• Total sales and order count for the current year
• Daily paid sales for the last 30 days
• Best-selling book (by units sold and revenue)
• Total registered users count
• New users registered during the current month
• User distribution by non-admin roles (user, seller, etc.)
• Orders grouped by order status (paid, pending, cancelled, etc.)
• Pending orders count
• Books with low inventory (stock <= 10)

Rate limit: 30 requests per minute.

Retrieves aggregated sales metrics for non-cancelled orders grouped by day, week, or month.

Optional query parameters allow filtering by date range (startDate and endDate) and selecting the aggregation period (groupBy):

• day: Groups data daily (YYYY-MM-DD) [default]
• week: Groups data weekly (YYYY-Www)
• month: Groups data monthly (YYYY-MM)

For each time bucket, the response returns:

• totalRevenue: Sum of total prices
• avgRevenue: Average order value
• totalOrders: Count of orders
• totalItems: Total quantity of books purchased

Rate limit: 30 requests per minute.

Returns three comprehensive analytical datasets across the bookstore:

1. booksAnalytic: Total books, active books, inactive/deleted books, out-of-stock books, and low-stock books (< 100 units).
2. bookSaleAnalytics: Top 10 best-selling books and top 10 low-selling books based on quantity sold in paid orders.
3. bookReviewAnalytics: Top 10 most-rated books and top 10 highest-rated books (by average rating).

Identifies stagnant inventory ("dead stock") books that have generated zero sales in paid orders over the past 30 days.

Returns paginated book items with title, author, current stock, price, and totalSold: 0.

Retrieves a paginated list of all books enriched with multi-dimensional performance data:

• orderAnalytics: Total units sold and total revenue from paid orders.
• wishlistAnalytics: Total times the book was wishlisted.
• bookRating: Average customer review rating.

Calculates total units sold (getSales) and cumulative revenue (getRevenue) across all paid orders, mapped across standard bookstore categories: Fantasy, Action, Adventure, Mystery, Horror, Thriller, Romance, Self-help, and Biography.

Categories without any sales return 0 for both fields.

Computes monthly sales quantities and revenue per category within a specified date range.

Validations enforced:

• startDate and endDate are required valid date strings.
• endDate must be strictly after startDate.
• The date range between startDate and endDate cannot exceed 1 year.

Missing calendar months in the range are automatically densified with zero values.

Aggregates customer reviews grouped by book, displaying individual counts for 5-star, 4-star, 3-star, 2-star, and 1-star ratings.

Results are paginated.

Returns two high-level order metrics:

1. orderStatusAnalytics: Total count of orders grouped by order status (e.g. paid, pending, cancelled).
2. orderCancellationAnalytics: Total orders, number of cancelled orders, and calculated cancellation rate percentage.

Provides day-by-day order counts between startDate and endDate.

Validations enforced:

• Both startDate and endDate are required.
• startDate cannot be later than endDate.
• The time difference between the dates cannot exceed 90 days.

Days without any order activity are automatically densified with a count of 0.

Calculates the monthly average order value (avgOrderValue), count of completed paid orders (completedOrders), and total revenue for paid orders within the specified date range.

Validations enforced:

• startDate and endDate are required.
• endDate must be strictly after startDate.
• Date range cannot exceed 1 year.

Months with zero orders return 0 for revenue and average order value.

Provides in-depth customer engagement and retention statistics:

1. userAnalytics: Monthly count of newly registered users over the date range (densified with 0).
2. topPayingCustomers: Top 10 customers ranked by total money spent on completed paid orders.
3. returningCustomers: Total unique buyers, count of repeat customers (> 1 paid order), and returning customer rate percentage.

Validations enforced:

• startDate and endDate are required.
• endDate must be greater than or equal to startDate.
• Date range cannot exceed 1 year.

Analyzes transaction history and financial performance across payment statuses:

• paymentStatusAnalytics: Volume counts and financial amounts partitioned into successful (paid), failed (failed), and refunded (cancelled) categories.
• paymentStatusRate: Total payment attempts, success rate percentage, and failure rate percentage rounded to two decimal places.

Restores and activates a suspended user account by setting isActive: true and persisting the change with user.save(). Once activated, the customer regains access to their account, can log in, and place bookstore orders.

Authentication & Access Control

• Required Authentication: Bearer JWT token in the Authorization header (protect middleware).
• Role Restriction: Strictly restricted to administrators (restrictTo("admin")).

Validation & Rate Limiting

• ID Validation: validateId("userId") validates that userId is a valid 24-character hexadecimal MongoDB ObjectId. Returns HTTP 400 Bad Request ("Invalid Id, please enter correct id") if malformed.
• Rate Limiting: Protected by mutationLimiter (maximum 10 mutation requests per minute) and router-level getRateLimiter (maximum 30 requests per minute).

Suspends and deactivates a user account by setting isActive: false using User.findByIdAndUpdate. Once deactivated, the user is blocked from logging in or performing customer operations, and excluded from public user queries.

Authentication & Access Control

• Required Authentication: Bearer JWT token in the Authorization header (protect middleware).
• Role Restriction: Strictly restricted to administrators (restrictTo("admin")).

Security & Business Constraints

• Self-Deactivation Guard: An administrator cannot suspend their own account (userId === req.user.id). Attempting to do so returns HTTP 400 Bad Request ("You can't deactivate your self").
• Admin Account Protection: Administrators cannot suspend other administrator accounts (user.role === 'admin'). Attempting to do so returns HTTP 400 Bad Request ("You can't deactivate admin user").

Validation & Rate Limiting

• ID Validation: validateId("userId") validates that userId is a valid 24-character hexadecimal MongoDB ObjectId. Returns HTTP 400 Bad Request ("Invalid Id, please enter correct id") if malformed.
• Rate Limiting: Protected by mutationLimiter (maximum 10 mutation requests per minute) and router-level getRateLimiter (maximum 30 requests per minute).

Changes the authorization role of a user account. Permits switching between "user" and "admin".

Authentication & Access Control

• Required Authentication: Bearer JWT token in the Authorization header (protect middleware).
• Role Restriction: Strictly restricted to administrators (restrictTo("admin")).

Security & Role Constraints

• Self-Role Modification Guard: An administrator cannot alter their own role (userId === req.user.id). Attempting to do so returns HTTP 400 Bad Request ("You can't change your role").
• Valid Role Enforcements: Only roles included in ["admin", "user"] are accepted. Any other string value triggers HTTP 400 Bad Request ("Please provide valid role").

Validation & Rate Limiting

• ID Validation: validateId("userId") validates that userId is a valid 24-character hexadecimal MongoDB ObjectId. Returns HTTP 400 Bad Request ("Invalid Id, please enter correct id") if malformed.
• Rate Limiting: Protected by mutationLimiter (maximum 10 mutation requests per minute) and router-level getRateLimiter (maximum 30 requests per minute).

Retrieves a paginated collection of active books from the catalog.

Supports keyword filtering by book title and author using case-insensitive regular expressions ($regex, $options: "i"). Results can be sorted in descending (newest) or ascending (oldest) chronological order by creation date.

Soft Deletion & Visibility

Soft-deleted books (isDeleted: true) are automatically excluded from the result set by a Mongoose pre(/^find/) query middleware.

Search & Filtering Capabilities

• Title Search: Substring match against book titles.
• Author Search: Substring match against author names.
• Both filters can be used independently or combined.

Sorting Behavior

• sort=new (default): Sorts descending by -createdAt (newest books first).
• sort=old: Sorts ascending by createdAt (oldest books first).
• Any unrecognized sort parameter defaults to new.

Pagination Rules

• page: 1-based page index (defaults to 1).
• limit: Number of records returned per page (defaults to 10).
• Upper Bound: If limit exceeds 100, the server automatically caps it at 100.
• Computes skip = (page - 1) * limit.
• Computes totalPages = Math.ceil(totalItems / limit) and hasNextPage = page < totalPages.

Rate Limiting

• Protected by getRateLimiter: Maximum 30 requests per minute per client IP.

Creates and registers a new book entity in the bookstore catalog.

This operation is restricted to verified administrators (role: 'admin'). The request must be transmitted as multipart/form-data to accommodate both book metadata fields and the binary image file for the book's cover.

Creation & Upload Flow

1. Authentication: Caller provides a valid JWT Bearer token in the Authorization header.
2. Authorization: restrictTo("admin") middleware verifies the caller holds admin role and that their email is verified.
3. Rate Limiting: mutationLimiter restricts the caller to 10 mutations per minute.
4. File Handling: Multer parses the multipart request, extracting the file from field coverImage and writing it to temporary disk storage (uploads/).
5. Validation: validateBooks validates the presence and constraints of title, author, stock, description, price, and category.
6. Cloudinary Upload: The server uploads the temporary cover image to Cloudinary under the "BookStore" folder.
7. Cleanup: The local temporary file is deleted from disk using fs.unlink.
8. Database Persistence: A new document is saved in MongoDB with the resulting Cloudinary HTTPS URL and initial defaults (totalSales: 0, ratingAverage: 0, ratingQuantity: 0, isDeleted: false).
9. Response: Returns HTTP 201 Created with the complete book document.

Validation Rules

• title: String, trimmed, non-empty, minimum length of 2 characters.
• author: String, non-empty.
• stock: Numeric, non-empty, non-negative integer.
• description: String, non-empty.
• price: Numeric, non-empty, non-negative, minimum length 1 character.
• category: Must match one of the predefined categories: Fantasy, Action, Adventure, Mystery, Horror, Thriller, Romance, Self-help, Biography. Cannot be empty.
• coverImage: Required binary file representing the book cover art.

Retrieves detailed information for a specific book identified by its unique MongoDB ObjectId.

High-Performance Redis Caching

This endpoint implements a cache-aside caching strategy using Redis:

1. The server checks for the Redis key book:{bookId}.
2. Cache Hit: If the key exists, cached JSON data is parsed and returned immediately without accessing the MongoDB database.
3. Cache Miss:
   • Validates that bookId parameter is present and valid.
   • Queries MongoDB via Books.findById(bookId).
   • The Mongoose pre(/^find/) middleware automatically filters out soft-deleted books (isDeleted: false).
   • If the book is not found in MongoDB, returns HTTP 404 Not Found.
   • If found, writes the serialized book document into Redis under book:{bookId} and returns HTTP 200 OK.

Rate Limiting

• Protected by getRateLimiter: Maximum 30 requests per minute per client IP.

Updates an existing book's metadata fields or replaces its cover image.

This operation is restricted to verified administrators (role: 'admin').

Update Workflow

1. ID Validation: validateId("bookId") middleware verifies that bookId is a syntactically valid 24-character hexadecimal MongoDB ObjectId.
2. Authentication & Authorization: protect and restrictTo("admin") ensure caller has active admin credentials.
3. Rate Limiting: mutationLimiter enforces a rate limit of 10 requests per minute.
4. Image Replacement (Optional): If a new coverImage file is attached via multipart/form-data:
   • The file is temporarily stored by Multer.
   • Uploaded to Cloudinary under the "BookStore" folder.
   • The local temporary file is removed via fs.unlink.
   • The new Cloudinary secure_url replaces the existing coverImage in the update payload.
5. Database Update: Calls Books.findByIdAndUpdate(bookId, updatePayload).
6. Cache Refresh: The updated book object is serialized and written to Redis key book:{bookId}, ensuring subsequent GET requests immediately reflect changes.
7. Response: Returns HTTP 200 OK with the updated book entity.

Request Formats Supported

• multipart/form-data: Use when replacing the cover image (with or without textual metadata changes).
• application/json: Use when updating only text or numeric fields (title, author, price, stock, description, category).

Performs a soft deletion on the book specified by bookId.

This operation is restricted to verified administrators (role: 'admin').

Soft-Deletion Architecture

Rather than permanently purging the record from MongoDB, the controller updates the document with { isDeleted: true }:

1. Preserves sales history, order relations, and aggregate analytics integrity.
2. Mongoose pre(/^find/) middleware automatically intercepts all queries (find, findOne, findById) and applies { isDeleted: false }, ensuring deleted books are immediately hidden from the public store catalog.
3. If the book does not exist or was already deleted, returns HTTP 404 Not Found.

Rate Limiting

• Protected by generalRateLimiter: Maximum 15 requests per minute per client IP.

Retrieves the active shopping cart for the authenticated customer.

This endpoint requires authentication and is restricted to customers with role: 'user'. The user's email address must be verified.

High-Performance Redis Caching Architecture

The cart utilizes a cache-aside caching strategy via Redis:

1. Cache Lookup: Checks Redis key user:{userId}:cart.
2. Cache Hit:
   • If cached data is present, the server parses the JSON string and responds immediately with HTTP 200 OK without touching the MongoDB database: { status: "success", message: "cart is found", data: cartData }.
3. Cache Miss:
   • Queries MongoDB for an existing cart via Cart.findOne({ user: userId }).
   • Writes the serialized result into Redis under key user:{userId}:cart.
   • If a cart exists in the database, returns HTTP 200 OK with { status: "success", data: getCart }.
   • If the user has not created or added any items to their cart yet, data is null.

Rate Limiting

• Protected by getRateLimiter: Maximum 30 requests per minute per client IP.