Updated changes in api-refactoring

docs/API-REFACTORING-2025-10-08.org

@@ -1,207 +0,0 @@
-#+TITLE: API Endpoint Refactoring - 2025-10-08
-#+AUTHOR: Cascade AI Assistant
-#+DATE: 2025-10-08
-
-* Overview
-
-Successfully refactored all API endpoints to use Radiance's built-in =define-api= macro following the framework's best practices and conventions.
-
-** What Changed
-- ✅ All API endpoints now use =define-api= (15 endpoints converted)
-- ✅ Web pages still use =define-page= (correct usage for rendering HTML)
-- ✅ Static file serving still uses =define-page= (correct usage)
-
-** Separation of Concerns
-- =define-api= → Used for all JSON API endpoints (data access)
-- =define-page= → Used for HTML page rendering and static file serving
-
-** Radiance's =define-api= Pattern
-
-Radiance's =define-api= signature:
-#+BEGIN_SRC lisp
-(define-api name (lambda-list) (options) body...)
-#+END_SRC
-
-Key features:
-- API endpoints are accessed at =/api/<name>= automatically
-- Parameters are specified in lambda-list (required and optional)
-- Uses =api-output= function for responses
-- Supports browser detection via =(post/get "browser")= for dual user/API usage
-- Automatic JSON serialization based on configured API format
-
-* Changes Made
-
-** Converted Endpoints to Radiance's =define-api=
-
-All API endpoints have been refactored from =define-page= with manual JSON handling to proper =define-api= definitions.
-
-*** Admin API Endpoints
-- =asteroid/admin/scan-library= → =/api/asteroid/admin/scan-library=
-- =asteroid/admin/tracks= → =/api/asteroid/admin/tracks=
-
-*** Playlist API Endpoints
-- =asteroid/playlists= → =/api/asteroid/playlists=
-- =asteroid/playlists/create= (params: name, description) → =/api/asteroid/playlists/create=
-- =asteroid/playlists/add-track= (params: playlist-id, track-id) → =/api/asteroid/playlists/add-track=
-- =asteroid/playlists/get= (param: playlist-id) → =/api/asteroid/playlists/get=
-
-*** Track API Endpoints
-- =asteroid/tracks= → =/api/asteroid/tracks=
-
-*** Player Control API Endpoints
-- =asteroid/player/play= (param: track-id) → =/api/asteroid/player/play=
-- =asteroid/player/pause= → =/api/asteroid/player/pause=
-- =asteroid/player/stop= → =/api/asteroid/player/stop=
-- =asteroid/player/resume= → =/api/asteroid/player/resume=
-- =asteroid/player/status= → =/api/asteroid/player/status=
-
-*** Status API Endpoints
-- =asteroid/auth-status= → =/api/asteroid/auth-status=
-- =asteroid/status= → =/api/asteroid/status=
-- =asteroid/icecast-status= → =/api/asteroid/icecast-status=
-
-** Pages Still Using =define-page= (Correct Usage)
-
-These continue to use =define-page= because they render HTML pages or serve files:
-
-*** HTML Pages
-- =front-page= - Main landing page (/)
-- =admin= - Admin dashboard (/admin)
-- =users-management= - User management page (/admin/user)
-- =user-profile= - User profile page (/profile)
-- =register= - Registration page (/register)
-- =player= - Web player page (/player)
-
-*** File Serving
-- =static= - Static file serving (/static/*)
-- =stream-track= - Audio file streaming (/tracks/*/stream)
-
-*** Helper Functions
-- =api-get-track-by-id= - Internal track lookup (not a public endpoint)
-
-* Benefits
-
-1. **Framework Compliance**: Now following Radiance's recommended patterns and best practices
-2. **Automatic Routing**: Endpoints automatically available at =/api/<name>= without manual URI configuration
-3. **Parameter Handling**: Clean lambda-list based parameter extraction instead of manual =post-var= calls
-4. **Dual Usage**: Built-in support for both programmatic API access and browser-based usage
-5. **Cleaner Code**: Uses =api-output= for consistent response formatting
-6. **Better Error Handling**: Proper HTTP status codes (404, 500, etc.) for different error conditions
-7. **Reduced Boilerplate**: No manual JSON encoding or header setting required
-
-* Code Examples
-
-** Before (using =define-page=):
-#+BEGIN_SRC lisp
-(define-page api-pause #@"/api/pause" ()
-  "Pause current playback"
-  (setf *player-state* :paused)
-  (setf (radiance:header "Content-Type") "application/json")
-  (cl-json:encode-json-to-string
-   `(("status" . "success")
-     ("message" . "Playback paused")
-     ("player" . ,(get-player-status)))))
-#+END_SRC
-
-** After (using Radiance's =define-api=):
-#+BEGIN_SRC lisp
-(define-api asteroid/player/pause () ()
-  "Pause current playback"
-  (setf *player-state* :paused)
-  (api-output `(("status" . "success")
-                ("message" . "Playback paused")
-                ("player" . ,(get-player-status)))))
-#+END_SRC
-
-** Example with Parameters:
-#+BEGIN_SRC lisp
-(define-api asteroid/playlists/create (name &optional description) ()
-  "Create a new playlist"
-  (require-authentication)
-  (handler-case
-      (let* ((user (get-current-user))
-             (user-id-raw (gethash "_id" user))
-             (user-id (if (listp user-id-raw) (first user-id-raw) user-id-raw)))
-        (create-playlist user-id name description)
-        (if (string= "true" (post/get "browser"))
-            (redirect "/asteroid/")
-            (api-output `(("status" . "success")
-                          ("message" . "Playlist created successfully")))))
-    (error (e)
-      (api-output `(("status" . "error")
-                    ("message" . ,(format nil "Error: ~a" e)))
-                  :status 500))))
-#+END_SRC
-
-* Testing Recommendations
-
-** API Endpoint URLs Changed
-All API endpoints now use the new URL structure. Update any frontend code or tests:
-
-Old format: =/api/tracks=
-New format: =/api/asteroid/tracks=
-
-** Testing Checklist
-1. Test all API endpoints with new URLs to ensure proper JSON responses
-2. Verify parameter passing works correctly (GET/POST parameters)
-3. Test browser detection: Add =browser=true= parameter to test redirect behavior
-4. Verify error handling returns proper HTTP status codes (404, 500, etc.)
-5. Check that authentication/authorization still works on protected endpoints
-6. Test endpoints both programmatically and via browser
-
-** Example Test Commands
-#+BEGIN_SRC bash
-# Test auth status
-curl http://localhost:8080/api/asteroid/auth-status
-
-# Test with parameters
-curl -X POST http://localhost:8080/api/asteroid/playlists/create \
-  -d "name=MyPlaylist&description=Test"
-
-# Test browser mode (should redirect)
-curl -X POST http://localhost:8080/api/asteroid/playlists/create \
-  -d "name=MyPlaylist&browser=true"
-
-# Test player control
-curl http://localhost:8080/api/asteroid/player/play?track-id=1
-#+END_SRC
-
-* Frontend Updates Required
-
-The frontend JavaScript code needs to be updated to use the new API endpoint URLs:
-
-** Files to Update
-- =static/js/profile.js= - Update API calls for playlists
-- =static/js/auth-ui.js= - Update auth-status endpoint
-- Any other JavaScript files making API calls
-
-** Example Changes
-#+BEGIN_SRC javascript
-// Old
-fetch('/api/playlists')
-
-// New
-fetch('/api/asteroid/playlists')
-#+END_SRC
-
-* Migration Notes
-
-** Breaking Changes
-- All API endpoint URLs have changed from =/api/<path>= to =/api/asteroid/<name>=
-- Parameters are now passed via GET/POST variables, not URI patterns
-- The =asteroid/playlists/get= endpoint now requires =playlist-id= as a parameter instead of URI pattern
-
-** Backward Compatibility
-Consider adding route redirects for old API URLs during transition period:
-#+BEGIN_SRC lisp
-(define-route old-api-redirect "/api/tracks" ()
-  (redirect "/api/asteroid/tracks"))
-#+END_SRC
-
-* Next Steps
-
-1. **Update Frontend Code**: Modify all JavaScript files to use new API URLs
-2. **Test Thoroughly**: Run through all user workflows to ensure APIs work correctly
-3. **Update Documentation**: Update any API documentation for external consumers
-4. **Monitor Logs**: Watch for any 404 errors indicating missed endpoint updates
-5. **Consider JSON Format**: May want to configure Radiance to use JSON API format instead of default S-expressions

docs/FRONTEND-API-UPDATES-2025-10-08.org

@@ -1,91 +0,0 @@
-#+TITLE: Frontend API URL Updates - 2025-10-08
-#+AUTHOR: Cascade AI Assistant
-#+DATE: 2025-10-08
-
-* Overview
-
-Updated all frontend JavaScript files to use the new Radiance =define-api= endpoint URLs.
-
-* URL Changes
-
-** Old Format
-=/asteroid/api/<endpoint>=
-
-** New Format
-=/api/asteroid/<endpoint>=
-
-* Files Updated
-
-** auth-ui.js
-- =/asteroid/api/auth-status= → =/api/asteroid/auth-status=
-
-** front-page.js
-- =/asteroid/api/icecast-status= → =/api/asteroid/icecast-status=
-
-** admin.js
-- =/asteroid/api/player-status= → =/api/asteroid/player/status=
-
-** player.js (Multiple Updates)
-- =/asteroid/api/tracks= → =/api/asteroid/tracks=
-- =/api/play?track-id=${id}= → =/api/asteroid/player/play?track-id=${id}=
-- =/asteroid/api/playlists/create= → =/api/asteroid/playlists/create=
-- =/asteroid/api/playlists= → =/api/asteroid/playlists=
-- =/asteroid/api/playlists/${id}= → =/api/asteroid/playlists/get?playlist-id=${id}= (Note: Changed from URI pattern to query parameter)
-- =/asteroid/api/playlists/add-track= → =/api/asteroid/playlists/add-track=
-- =/asteroid/api/icecast-status= → =/api/asteroid/icecast-status=
-
-* Important Changes
-
-** Playlist Get Endpoint
-The playlist retrieval endpoint changed from a URI pattern to a query parameter:
-
-Old: =GET /asteroid/api/playlists/123=
-New: =GET /api/asteroid/playlists/get?playlist-id=123=
-
-This aligns with Radiance's =define-api= pattern where parameters are passed as GET/POST variables rather than URI patterns.
-
-* Files Not Updated
-
-** users.js
-This file contains API calls to user management endpoints that don't exist in the backend yet:
-- =/asteroid/api/users/stats=
-- =/asteroid/api/users=
-- =/asteroid/api/users/${id}/role=
-- =/asteroid/api/users/${id}/deactivate=
-- =/asteroid/api/users/${id}/activate=
-- =/asteroid/api/users/create=
-
-These endpoints will need to be implemented using =define-api= when user management features are added.
-
-** profile.js
-This file contains API calls to user profile endpoints that are currently commented out in the backend:
-- =/asteroid/api/user/profile=
-- =/asteroid/api/user/listening-stats=
-- =/asteroid/api/user/recent-tracks=
-- =/asteroid/api/user/top-artists=
-- =/asteroid/api/user/export-data=
-- =/asteroid/api/user/clear-history=
-
-These will need to be updated once the profile API endpoints are implemented with =define-api=.
-
-* Testing Checklist
-
-- [X] Update auth-ui.js
-- [X] Update front-page.js
-- [X] Update admin.js
-- [X] Update player.js
-- [ ] Test authentication flow
-- [ ] Test track loading and playback
-- [ ] Test playlist creation
-- [ ] Test playlist loading (with new query parameter format)
-- [ ] Test adding tracks to playlists
-- [ ] Test Icecast status updates
-- [ ] Implement and test user management APIs
-- [ ] Implement and test user profile APIs
-
-* Next Steps
-
-1. **Test the Application**: Start the server and test all functionality
-2. **Implement Missing APIs**: Create user management and profile APIs using =define-api=
-3. **Update Remaining Files**: Once APIs are implemented, update users.js and profile.js
-4. **Monitor Console**: Check browser console for any 404 errors indicating missed endpoints

docs/TESTING.org

@@ -1,271 +0,0 @@
-#+TITLE: Asteroid Radio Testing Guide
-#+AUTHOR: Cascade AI Assistant
-#+DATE: 2025-10-08
-
-* Overview
-
-This document describes the automated testing system for Asteroid Radio.
-
-* Test Script
-
-The =test-server.sh= script provides comprehensive testing of all server endpoints and functionality.
-
-** Features
-
-- Tests all API endpoints (15 endpoints)
-- Tests HTML page rendering (5 pages)
-- Tests static file serving
-- Validates JSON response format
-- Color-coded output for easy reading
-- Detailed pass/fail reporting
-- Verbose mode for debugging
-
-** Usage
-
-*** Basic Usage
-#+BEGIN_SRC bash
-# Test local server (default: http://localhost:8080)
-./test-server.sh
-
-# Verbose mode (shows response details)
-./test-server.sh -v
-
-# Test remote server
-./test-server.sh -u http://example.com
-
-# Show help
-./test-server.sh -h
-#+END_SRC
-
-*** Environment Variables
-#+BEGIN_SRC bash
-# Set base URL via environment
-ASTEROID_URL=http://example.com ./test-server.sh
-
-# Enable verbose mode
-VERBOSE=1 ./test-server.sh
-#+END_SRC
-
-** Test Categories
-
-*** 1. Server Status
-- Server accessibility check
-- API response format validation
-
-*** 2. Status Endpoints
-- =/api/asteroid/status= - Server status
-- =/api/asteroid/auth-status= - Authentication status
-- =/api/asteroid/icecast-status= - Icecast streaming status
-
-*** 3. Track Endpoints
-- =/api/asteroid/tracks= - Track listing
-- =/api/asteroid/admin/tracks= - Admin track listing
-
-*** 4. Player Control Endpoints
-- =/api/asteroid/player/status= - Player status
-- =/api/asteroid/player/play= - Play track
-- =/api/asteroid/player/pause= - Pause playback
-- =/api/asteroid/player/stop= - Stop playback
-- =/api/asteroid/player/resume= - Resume playback
-
-*** 5. Playlist Endpoints
-- =/api/asteroid/playlists= - Playlist listing
-- =/api/asteroid/playlists/create= - Create playlist
-- =/api/asteroid/playlists/add-track= - Add track to playlist
-- =/api/asteroid/playlists/get= - Get playlist details
-
-*** 6. Admin Endpoints
-- =/api/asteroid/admin/tracks= - Admin track listing
-- =/api/asteroid/admin/scan-library= - Library scan
-
-*** 7. HTML Pages
-- =/asteroid/= - Front page
-- =/asteroid/admin= - Admin dashboard
-- =/asteroid/player= - Web player
-- =/asteroid/profile= - User profile
-- =/asteroid/register= - Registration page
-
-*** 8. Static Files
-- CSS files (=/asteroid/static/*.css=)
-- JavaScript files (=/asteroid/static/js/*.js=)
-
-** Example Output
-
-#+BEGIN_EXAMPLE
-╔═══════════════════════════════════════╗
-║  Asteroid Radio Server Test Suite    ║
-╔═══════════════════════════════════════╗
-
-INFO: Testing server at: http://localhost:8080
-INFO: Verbose mode: 0
-
-========================================
-Checking Server Status
-========================================
-
-TEST: Server is accessible
-✓ PASS: Server is running at http://localhost:8080
-
-========================================
-Testing API Response Format
-========================================
-
-TEST: API returns JSON format
-✓ PASS: API returns JSON (not S-expressions)
-
-========================================
-Testing Status Endpoints
-========================================
-
-TEST: Server status endpoint
-✓ PASS: Server status endpoint - Response contains 'asteroid-radio'
-
-TEST: Authentication status endpoint
-✓ PASS: Authentication status endpoint - Response contains 'loggedIn'
-
-...
-
-========================================
-Test Summary
-========================================
-
-Tests Run:    25
-Tests Passed: 25
-Tests Failed: 0
-
-✓ All tests passed!
-#+END_EXAMPLE
-
-** Exit Codes
-
-- =0= - All tests passed
-- =1= - One or more tests failed or server not accessible
-
-** Requirements
-
-*** Required
-- =bash= - Shell script interpreter
-- =curl= - HTTP client for testing endpoints
-
-*** Optional
-- =jq= - JSON processor for advanced JSON validation (recommended)
-
-Install jq:
-#+BEGIN_SRC bash
-# Ubuntu/Debian
-sudo apt install jq
-
-# macOS
-brew install jq
-#+END_SRC
-
-** Integration with CI/CD
-
-The test script can be integrated into continuous integration pipelines:
-
-#+BEGIN_SRC yaml
-# Example GitHub Actions workflow
-- name: Start Asteroid Server
-  run: ./asteroid &
-  
-- name: Wait for server
-  run: sleep 5
-
-- name: Run tests
-  run: ./test-server.sh
-#+END_SRC
-
-** Extending the Tests
-
-To add new tests, edit =test-server.sh= and add test functions:
-
-#+BEGIN_SRC bash
-test_my_new_feature() {
-    print_header "Testing My New Feature"
-    
-    test_api_endpoint "/my-endpoint" \
-        "My endpoint description" \
-        "expected-field"
-}
-
-# Add to main() function
-main() {
-    # ... existing tests ...
-    test_my_new_feature
-    # ...
-}
-#+END_SRC
-
-** Troubleshooting
-
-*** Server not accessible
-- Ensure server is running: =./asteroid=
-- Check server is on correct port: =8080=
-- Verify firewall settings
-
-*** Tests failing
-- Run with verbose mode: =./test-server.sh -v=
-- Check server logs for errors
-- Verify database is initialized
-- Ensure all dependencies are installed
-
-*** JSON format issues
-- Verify JSON API format is configured in =asteroid.lisp=
-- Check =define-api-format json= is defined
-- Ensure =*default-api-format*= is set to ="json"=
-
-* Manual Testing Checklist
-
-For features not covered by automated tests:
-
-** Authentication
-- [ ] Login with admin/asteroid123
-- [ ] Logout functionality
-- [ ] Session persistence
-- [ ] Protected pages redirect to login
-
-** Music Library
-- [ ] Scan library adds tracks
-- [ ] Track metadata displays correctly
-- [ ] Audio streaming works
-- [ ] Search and filter tracks
-
-** Playlists
-- [ ] Create new playlist
-- [ ] Add tracks to playlist
-- [ ] Load playlist
-- [ ] Delete playlist
-
-** Player
-- [ ] Play/pause/stop controls work
-- [ ] Track progress updates
-- [ ] Queue management
-- [ ] Volume control
-
-** Admin Features
-- [ ] View all tracks
-- [ ] Scan library
-- [ ] User management
-- [ ] System status monitoring
-
-* Performance Testing
-
-For load testing and performance validation:
-
-#+BEGIN_SRC bash
-# Simple load test with Apache Bench
-ab -n 1000 -c 10 http://localhost:8080/api/asteroid/tracks
-
-# Or with wrk
-wrk -t4 -c100 -d30s http://localhost:8080/api/asteroid/tracks
-#+END_SRC
-
-* Security Testing
-
-** API Security Checklist
-- [ ] Authentication required for protected endpoints
-- [ ] Authorization checks for admin endpoints
-- [ ] SQL injection prevention
-- [ ] XSS protection in templates
-- [ ] CSRF token validation
-- [ ] Rate limiting on API endpoints