Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: add Carousel dashboard implementation plan

Browse Source
This commit is contained in:
john-okeefe
2026-02-17 17:00:46 -05:00
parent fce16b53f7
commit 96730d9475
407 changed files with 10834 additions and 10983 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bruno/user/admin/Delete Account.bru
-53
View File
@@ -1,53 +0,0 @@
meta {
name: Delete Account
type: http
seq: 4
}
delete {
url: {{base_url}}/api/auth/account
body: none
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Delete Account
Permanently deletes user account and all associated data.
**Method:** DELETE
**Endpoint:** /api/auth/account
**Authentication:** Required
**Usage:**
- **Self-deletion**: DELETE /api/auth/account (no parameters)
- **Admin deletion**: DELETE /api/auth/account?user_id={uuid} (admin only)
**Query Parameters (Admin only):**
- `user_id` (string): UUID of user account to delete
**Response:**
- `message` (string): Success message
**Status Codes:**
- 200: Success
- 400: Bad Request (invalid user_id or attempting to delete last admin)
- 401: Unauthorized
- 403: Forbidden (admin access required for user_id parameter)
- 404: Not Found (user does not exist)
**Protection Rules:**
- Regular users can only delete their own account
- Admins can delete any account including other users
- Cannot delete the last admin account in the system
- Admin role required to use user_id parameter
**Warning:** This action cannot be undone and will permanently delete all user data including media items, ratings, and progress.
}
bruno/user/admin/Delete User Account (Admin).bru
-54
View File
@@ -1,54 +0,0 @@
meta {
name: Delete User Account (Admin)
type: http
seq: 6
}
delete {
url: {{base_url}}/api/auth/account?user_id={{user_id}}
body: none
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Delete User Account (Admin)
Allows administrators to delete any user account by specifying user_id parameter.
**Method:** DELETE
**Endpoint:** /api/auth/account?user_id={user_id}
**Authentication:** Required (Admin only)
**Query Parameters:**
- `user_id` (string, required for admin): UUID of the user account to delete
**Usage Examples:**
- **Self-deletion**: DELETE /api/auth/account (no user_id parameter)
- **Admin deletion**: DELETE /api/auth/account?user_id=550e8400-e29b-41d4-a716-446655440000
**Response:**
- `message` (string): Success message indicating which account was deleted
**Status Codes:**
- 200: Success
- 400: Bad Request (invalid user_id or attempting to delete last admin)
- 401: Unauthorized
- 403: Forbidden (admin access required for user_id parameter)
- 404: Not Found (user does not exist)
**Admin Protection Rules:**
- Regular users can only delete their own account (no user_id parameter allowed)
- Admins can delete any account including their own
- Cannot delete the last admin account in the system
- Admin role required to use user_id parameter
**Variables:**
- `user_id`: Set this to the UUID of the user you want to delete
}
bruno/user/admin/List Users.bru
-99
View File
@@ -1,99 +0,0 @@
meta {
name: List Users
type: http
seq: 5
}
get {
url: {{base_url}}/api/auth/users
body: none
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## List Users
Retrieves a list of all users with complete user information.
**Method:** GET
**Endpoint:** /api/auth/users
**Authentication:** Required (Admin only)
**Response:** Array of user objects with complete information:
- `id` (string): User ID (UUID)
- `email` (string): Email address
- `username` (string): Username
- `first_name` (string): First name (empty if not set)
- `last_name` (string): Last name (empty if not set)
- `role` (string): User role ("user" or "admin")
- `theme` (string): Theme preference (empty if default)
- `max_devices` (integer): Maximum number of devices allowed
- `device_count` (integer): Current number of registered devices
- `created_at` (string): Creation timestamp (ISO 8601)
- `updated_at` (string): Last update timestamp (ISO 8601)
**Status Codes:**
- 200: Success
- 401: Unauthorized
- 403: Forbidden (admin access required)
**Features:**
- Admin-only endpoint with complete user information
- Returns first_name, last_name, role, theme fields
- Includes device limits and current device count
- Useful for user management interfaces
}
get {
url: {{base_url}}/api/auth/users
body: none
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## List Users (Admin)
Retrieves a list of all users with complete user information.
**Method:** GET
**Endpoint:** /api/auth/users
**Authentication:** Required (Admin only)
**Response:** Array of user objects with complete information:
- `id` (string): User ID (UUID)
- `email` (string): Email address
- `username` (string): Username
- `first_name` (string): First name (empty if not set)
- `last_name` (string): Last name (empty if not set)
- `role` (string): User role ("user" or "admin")
- `theme` (string): Theme preference (empty if default)
- `max_devices` (integer): Maximum number of devices allowed
- `device_count` (integer): Current number of registered devices
- `created_at` (string): Creation timestamp (ISO 8601)
- `updated_at` (string): Last update timestamp (ISO 8601)
**Status Codes:**
- 200: Success
- 401: Unauthorized
- 403: Forbidden (admin access required)
**Enhanced Features:**
- Now admin-only endpoint (moved from public to protected admin group)
- Returns complete user profile information including names and role
- Includes device limits and current device count for monitoring
- Useful for comprehensive admin user management
}
bruno/user/admin/Register Admin User.bru
-87
View File
@@ -1,87 +0,0 @@
meta {
name: Register Admin User
type: http
seq: 4
}
post {
url: {{base_url}}/api/auth/register
body: json
auth: inherit
}
body:json {
{
"email": "maxdevices@example.com",
"username": "maxdevicesuser",
"password": "Test@Pass123!",
"first_name": "Test",
"last_name": "User",
"role": "admin"
}
}
script:post-response {
function onResponse(res) {
let data = res.getBody();
return bru.setEnvVar("token", data.token, { persist: true });
}
onResponse(res);
}
// Test admin user aligns with Go integration tests
// Email: maxdevices@example.com used in device cap tests
// See TEST_DATA.md for shared test data documentation
settings {
encodeUrl: true
timeout: 0
}
docs {
## Register Admin User
Creates a new admin user account with role-based restrictions.
**Method:** POST
**Endpoint:** /api/auth/register
**Request Body:**
- `email` (string): Email address
- `username` (string): Username
- `password` (string): Password
- `first_name` (string, optional): First name
- `last_name` (string, optional): Last name
- `role` (string): Must be "admin"
**Response:**
- `token` (string): JWT token with admin role
- `user` (object): User details
- `id` (string): User ID
- `email` (string): Email
- `username` (string): Username
- `theme` (string): User theme preference
- `first_name` (string, optional): First name
- `last_name` (string, optional): Last name
- `role` (string): User role ("admin")
**Status Codes:**
- 201: Created
- 400: Invalid input data
- 403: Forbidden - admin creation restrictions apply
- 409: User exists
**Role Restrictions:**
- **First User**: Anyone can create first admin (auto-assigned)
- **Existing Admins Present**: Only authenticated admins can create new admin accounts
- **Unauthenticated Users**: Cannot create admin accounts if any admin exists
- **Security**: Requires admin authentication for subsequent admin creation
**Usage Notes:**
- Use this request only when specifically creating admin accounts
- For regular user creation, use "Register User" request
- Admin token will have elevated privileges for administrative operations
}
bruno/user/admin/Update User Max Devices - Invalid Too High.bru
-32
View File
@@ -1,32 +0,0 @@
meta {
name: Update User Max Devices - Exceeds Maximum
type: http
seq: 3
}
put {
url: {{base_url}}/api/auth/users/{{user_id}}/max-devices
body: {
max_devices: 101
}
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
vars {
user_id: 123e4567-e89b-12d3-a456-426614174000
max_devices: 101
}
docs {
## Update User Max Devices - Invalid (Exceeds Maximum)
Attempts to set max_devices to 101 (above maximum of 100).
**Expected:** 400 Bad Request
**Response:** `{"error": "validation error"}`
}
bruno/user/admin/Update User Max Devices - Invalid Zero.bru
-32
View File
@@ -1,32 +0,0 @@
meta {
name: Update User Max Devices - Invalid Max Devices
type: http
seq: 2
}
put {
url: {{base_url}}/api/auth/users/{{user_id}}/max-devices
body: {
max_devices: 0
}
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
vars {
user_id: 123e4567-e89b-12d3-a456-426614174000
max_devices: 0
}
docs {
## Update User Max Devices - Invalid (Zero)
Attempts to set max_devices to 0 (below minimum).
**Expected:** 400 Bad Request
**Response:** `{"error": "validation error"}`
}
bruno/user/admin/Update User Max Devices - Missing ID.bru
-27
View File
@@ -1,27 +0,0 @@
meta {
name: Update User Max Devices - Missing ID
type: http
seq: 4
}
put {
url: {{base_url}}/api/auth/users//max-devices
body: {
max_devices: 10
}
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Update User Max Devices - Missing User ID
Attempts to update max devices without providing user ID.
**Expected:** 400 Bad Request
**Response:** `{"error": "user id required"}`
}
bruno/user/admin/Update User Max Devices - Success.bru
-32
View File
@@ -1,32 +0,0 @@
meta {
name: Update User Max Devices - Success
type: http
seq: 1
}
put {
url: {{base_url}}/api/auth/users/{{user_id}}/max-devices
body: {
max_devices: 5
}
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
vars {
user_id: 123e4567-e89b-12d3-a456-426614174000
max_devices: 5
}
docs {
## Update User Max Devices - Success Case
Successfully updates a user's max devices limit to 5.
**Expected:** 200 OK
**Response:** `{"message": "max devices updated"}`
}
bruno/user/admin/Update User Max Devices.bru
-95
View File
@@ -1,95 +0,0 @@
meta {
name: Update User Max Devices
type: http
seq: 6
}
put {
url: {{base_url}}/api/auth/users/{{user_id}}/max-devices
body: {
max_devices: {{max_devices}}
}
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Update User Max Devices (Admin)
Updates the maximum number of devices a user can register.
**Method:** PUT
**Endpoint:** /api/auth/users/:id/max-devices
**Authentication:** Required (Admin only)
**URL Parameters:**
- `id` (string): User ID (UUID)
**Request Body:**
```json
{
"max_devices": 10
}
```
- `max_devices` (integer, required): Maximum devices (1-100)
**Response:**
```json
{
"message": "max devices updated"
}
```
**Status Codes:**
- 200: Success
- 400: Invalid request (missing id, invalid max_devices, out of range)
- 401: Unauthorized
- 403: Forbidden (admin access required)
- 500: Internal server error
**Validation:**
- `max_devices` must be between 1 and 100
- User ID must be a valid UUID
- User must exist
**Features:**
- Admin-only endpoint for managing user device quotas
- Allows per-user device limits (default: 10)
- Prevents excessive device registrations per user
- Useful for multi-tenant or managed deployments
**Examples:**
Set max devices to 5:
```json
{
"max_devices": 5
}
```
Set max devices to 50 (premium user):
```json
{
"max_devices": 50
}
```
Set max devices to 1 (restricted user):
```json
{
"max_devices": 1
}
```
**Use Cases:**
- Restrict free-tier users to 5 devices
- Allow premium users up to 100 devices
- Reduce device cap for suspicious accounts
- Implement tiered device limits per user plan
}
bruno/user/auth/Login User.bru
-50
View File
@@ -1,50 +0,0 @@
meta {
name: Login User
type: http
seq: 1
}
post {
url: {{base_url}}/api/auth/login
body: json
}
body:json {
{
"login": "testuser@example.com",
"password": "Test@Pass123!"
}
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Login User
Authenticates a user with email/username and password.
**Method:** POST
**Endpoint:** /api/auth/login
**Request Body:**
- `login` (string): Email or username
- `password` (string): Password
**Response:**
- `token` (string): JWT token
- `user` (object): User details
- `id` (string): User ID
- `email` (string): Email
- `username` (string): Username
- `theme` (string): User theme preference
- `first_name` (string): First name
- `last_name` (string): Last name
**Status Codes:**
- 200: Success
- 401: Invalid credentials
}
bruno/user/auth/Logout User.bru
-57
View File
@@ -1,57 +0,0 @@
meta {
name: Logout User
type: http
seq: 1
}
post {
url: {{base_url}}/api/auth/logout
body: json
auth: inherit
}
headers {
Content-Type: application/json
}
body:json {
{
"refresh_token": "{{refresh_token}}"
}
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Logout User
Logs out the user by revoking their refresh token. If no refresh token is provided, the request succeeds but no token is revoked.
**Method:** POST
**Endpoint:** /api/auth/logout
**Authentication:** Bearer token (optional)
**Request Body:**
- `refresh_token` (string, optional): Refresh token to revoke
**Response:**
- `message` (string): Success message
**Status Codes:**
- 200: Success - user logged out (token revoked if provided)
- 401: Unauthorized
**Example Response:**
```json
{
"message": "logged out successfully"
}
```
**Note:** The access token will expire naturally after 1 hour. The refresh token is immediately revoked on logout, preventing future token refreshes.
}
bruno/user/auth/Refresh Token.bru
-68
View File
@@ -1,68 +0,0 @@
meta {
name: Refresh Access Token
type: http
seq: 1
}
post {
url: {{base_url}}/api/auth/refresh
body: json
auth: inherit
}
headers {
Content-Type: application/json
}
body:json {
{
"refresh_token": "{{refresh_token}}"
}
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Refresh Access Token
Refreshes an access token using a valid refresh token. Returns a new access token with 1-hour expiration.
**Method:** POST
**Endpoint:** /api/auth/refresh
**Authentication:** Not required (refresh token is in request body)
**Request Body:**
- `refresh_token` (string): Valid refresh token UUID
**Response:**
- `access_token` (string): New JWT access token (1 hour expiration)
- `token_type` (string): Token type (usually "Bearer")
- `expires_in` (number): Token lifetime in seconds (3600)
**Status Codes:**
- 200: Success - new access token generated
- 401: Unauthorized - invalid or expired refresh token
**Example Response (Success):**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
```
**Example Response (Invalid Token):**
```json
{
"error": "invalid or expired refresh token"
}
```
**Note:** Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring the user to log in again.
}
bruno/user/auth/Register User.bru
-90
View File
@@ -1,90 +0,0 @@
meta {
name: Register User
type: http
seq: 2
}
post {
url: {{base_url}}/api/auth/register
body: json
auth: inherit
}
body:json {
{
"email": "testuser@example.com",
"username": "testuser",
"password": "Test@Pass123!",
"first_name": "Test",
"last_name": "User"
}
}
// Test user aligns with Go integration tests
// See TEST_DATA.md for shared test data documentation
script:post-response {
function onResponse(res) {
let data = res.getBody();
// If successful registration, set token environment variable
if (res.getStatus() === 201 || res.getStatus() === 200) {
if (data && data.access_token) {
return bru.setEnvVar("token", data.access_token, { persist: true });
}
}
}
onResponse(res);
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Register User
Creates a new user account with role-based restrictions.
**Method:** POST
**Endpoint:** /api/auth/register
**Request Body:**
- `email` (string): Email address
- `username` (string): Username
- `password` (string): Password
- `first_name` (string, optional): First name
- `last_name` (string, optional): Last name
- `role` (string): User role ("user" or "admin")
**Response:**
- `token` (string): JWT token
- `user` (object): User details
- `id` (string): User ID
- `email` (string): Email
- `username` (string): Username
- `theme` (string): User theme preference
- `first_name` (string, optional): First name
- `last_name` (string, optional): Last name
- `role` (string): User role ("user" or "admin")
**Status Codes:**
- 201: Created
- 400: Invalid input data
- 403: Forbidden - role-based restrictions apply
- 409: User exists
**Role Restrictions:**
- **First User**: Automatically gets admin role regardless of request
- **Existing Admins Present**: Only authenticated admins can create new admin accounts
- **No Admins Yet**: Anyone can create first admin (auto-assigned)
- **Regular User Creation**: Anyone can create regular user accounts
- **Unauthenticated Users**: Can only create first admin, not subsequent admins
**Examples:**
- First admin creation: `{"email": "admin@example.com", "username": "admin", "password": "password123", "role": "admin"}`
- Regular user creation: `{"email": "user@example.com", "username": "user", "password": "password123", "role": "user"}`
}
bruno/user/profile/Get Profile.bru
-40
View File
@@ -1,40 +0,0 @@
meta {
name: Get Profile
type: http
seq: 1
}
get {
url: {{base_url}}/api/auth/profile
body: none
auth: inherit
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Get User Profile
Retrieves the authenticated user's profile.
**Method:** GET
**Endpoint:** /api/auth/profile
**Authentication:** Required
**Response:**
- `id` (string): User ID
- `email` (string): Email
- `username` (string): Username
- `theme` (string): User theme preference
- `first_name` (string, optional): First name
- `last_name` (string, optional): Last name
**Status Codes:**
- 200: Success
- 401: Unauthorized
}
bruno/user/profile/Update Email.bru
-46
View File
@@ -1,46 +0,0 @@
meta {
name: Update Email
type: http
seq: 2
}
put {
url: {{base_url}}/api/auth/email
body: json
auth: inherit
}
body {
{
"email": "newemail@example.com"
}
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Update Email
Updates the authenticated user's email address.
**Method:** PUT
**Endpoint:** /api/auth/email
**Authentication:** Required
**Request Body:**
- `email` (string, required): New email address (must be valid email format)
**Response:**
- `message` (string): Success message
**Status Codes:**
- 200: Success
- 400: Invalid email format
- 401: Unauthorized
- 409: Email already taken
}
bruno/user/profile/Update Password.bru
-50
View File
@@ -1,50 +0,0 @@
meta {
name: Update Password
type: http
seq: 3
}
put {
url: {{base_url}}/api/auth/password
body: json
auth: inherit
}
body:json {
{
"current_password": "password123",
"new_password": "newpassword123",
"confirm_password": "newpassword123"
}
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Update Password
Updates the authenticated user's password.
**Method:** PUT
**Endpoint:** /api/auth/password
**Authentication:** Required
**Request Body:**
- `current_password` (string, required): Current password for verification
- `new_password` (string, required): New password (minimum 6 characters)
- `confirm_password` (string, required): Confirmation of new password
**Response:**
- `message` (string): Success message
**Status Codes:**
- 200: Success
- 400: Password validation failed
- 401: Current password incorrect
- 401: Unauthorized
}
bruno/user/profile/Update Profile.bru
-47
View File
@@ -1,47 +0,0 @@
meta {
name: Update Profile
type: http
seq: 4
}
put {
url: {{base_url}}/api/auth/profile
body: json
auth: inherit
}
body:json {
{
"first_name": "Updated",
"last_name": "Name"
}
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Update User Profile
Updates the authenticated user's profile information.
**Method:** PUT
**Endpoint:** /api/auth/profile
**Authentication:** Required (Bearer token)
**Request Body:**
- `first_name` (string, optional): First name
- `last_name` (string, optional): Last name
**Response:**
- `message` (string): Success message
**Status Codes:**
- 200: Success
- 400: Invalid request
- 401: Unauthorized
}
bruno/user/profile/Update Theme.bru
-40
View File
@@ -1,40 +0,0 @@
meta {
name: Update Theme
type: http
seq: 4
}
put {
url: {{base_url}}/api/auth/theme
body: json
auth: inherit
}
body:json {
{
"theme": "dracula"
}
}
docs {
## Update User Theme
Updates the authenticated user's theme preference.
**Method:** PUT
**Endpoint:** /api/auth/theme
**Authentication:** Required (Bearer token)
**Request Body:**
- `theme` (string): Theme name (tokyo-night, dracula, nord, solarized-dark, monokai, one-dark-pro, material-dark, catppuccin-mocha, catppuccin-macchiato, catppuccin-frappe, catppuccin-latte)
**Response:**
- `message` (string): Success message
**Status Codes:**
- 200: Success
- 400: Invalid theme
- 401: Unauthorized
}
bruno/user/profile/Update Username.bru
-46
View File
@@ -1,46 +0,0 @@
meta {
name: Update Username
type: http
seq: 1
}
put {
url: {{base_url}}/api/auth/username
body: json
auth: inherit
}
body {
{
"username": "newusername"
}
}
settings {
encodeUrl: true
timeout: 0
}
docs {
## Update Username
Updates the authenticated user's username.
**Method:** PUT
**Endpoint:** /api/auth/username
**Authentication:** Required
**Request Body:**
- `username` (string, required): New username (3-50 characters)
**Response:**
- `message` (string): Success message
**Status Codes:**
- 200: Success
- 400: Invalid username
- 401: Unauthorized
- 409: Username already taken
}