refactor: remove SongBrowser module and controller, update SongController to enhance song retrieval with detailed query options

Author: tomast1337

apps/backend/src/app.module.ts

@@ -14,7 +14,6 @@ import { ParseTokenPipe } from './lib/parseToken';
 import { MailingModule } from './mailing/mailing.module';
 import { SeedModule } from './seed/seed.module';
 import { SongModule } from './song/song.module';
-import { SongBrowserModule } from './song-browser/song-browser.module';
 import { UserModule } from './user/user.module';
 
 @Module({

apps/backend/src/song-browser/song-browser.controller.spec.ts

@@ -36,6 +36,9 @@ import {
   ApiBody,
   ApiConsumes,
   ApiOperation,
+  ApiParam,
+  ApiQuery,
+  ApiResponse,
   ApiTags,
 } from '@nestjs/swagger';
 import type { Response } from 'express';
@@ -51,14 +54,10 @@ import { SongService } from './song.service';
 @ApiTags('song')
 export class SongController {
   static multerConfig: MulterOptions = {
-    limits: {
-      fileSize: UPLOAD_CONSTANTS.file.maxSize,
-    },
+    limits: { fileSize: UPLOAD_CONSTANTS.file.maxSize },
     fileFilter: (req, file, cb) => {
-      if (!file.originalname.match(/\.(nbs)$/)) {
+      if (!file.originalname.match(/\.(nbs)$/))
         return cb(new Error('Only .nbs files are allowed!'), false);
-      }
-
       cb(null, true);
     },
   };
@@ -71,7 +70,89 @@ export class SongController {
 
   @Get('/')
   @ApiOperation({
-    summary: 'Get a filtered/sorted list of songs with pagination',
+    summary: 'Get songs with various filtering and browsing options',
+    description: `
+      Retrieves songs based on the provided query parameters. Supports multiple modes:
+      
+      **Default mode** (no 'q' parameter): Returns paginated songs with sorting/filtering
+      
+      **Special query modes** (using 'q' parameter):
+      - \`featured\`: Get recent popular songs with pagination
+      - \`recent\`: Get recently uploaded songs with pagination  
+      - \`categories\`: 
+        - Without 'id': Returns a record of available categories and their song counts
+        - With 'id': Returns songs from the specified category with pagination
+      - \`random\`: Returns random songs (requires 'count' parameter, 1-10 songs, optionally filtered by 'category')
+      
+      **Query Parameters:**
+      - Standard pagination/sorting via PageQueryDTO (page, limit, sort, order, timespan)
+      - \`q\`: Special query mode ('featured', 'recent', 'categories', 'random')
+      - \`id\`: Category ID (used with q=categories to get songs from specific category)
+      - \`count\`: Number of random songs to return (1-10, used with q=random)
+      - \`category\`: Category filter for random songs (used with q=random)
+      
+      **Return Types:**
+      - SongPreviewDto[]: Array of song previews (most cases)
+      - Record<string, number>: Category name to count mapping (when q=categories without id)
+    `,
+  })
+  @ApiQuery({
+    name: 'q',
+    required: false,
+    enum: ['featured', 'recent', 'categories', 'random'],
+    description:
+      'Special query mode. If not provided, returns standard paginated song list.',
+    example: 'recent',
+  })
+  @ApiParam({
+    name: 'id',
+    required: false,
+    type: 'string',
+    description:
+      'Category ID. Only used when q=categories to get songs from a specific category.',
+    example: 'pop',
+  })
+  @ApiQuery({
+    name: 'count',
+    required: false,
+    type: 'string',
+    description:
+      'Number of random songs to return (1-10). Only used when q=random.',
+    example: '5',
+  })
+  @ApiQuery({
+    name: 'category',
+    required: false,
+    type: 'string',
+    description: 'Category filter for random songs. Only used when q=random.',
+    example: 'electronic',
+  })
+  @ApiResponse({
+    status: 200,
+    description:
+      'Success. Returns either an array of song previews or category counts.',
+    schema: {
+      oneOf: [
+        {
+          type: 'array',
+          items: { $ref: '#/components/schemas/SongPreviewDto' },
+          description:
+            'Array of song previews (default behavior and most query modes)',
+        },
+        {
+          type: 'object',
+          additionalProperties: { type: 'number' },
+          description:
+            'Category name to song count mapping (only when q=categories without id)',
+          example: { pop: 42, rock: 38, electronic: 15 },
+        },
+      ],
+    },
+  })
+  @ApiResponse({
+    status: 400,
+    description:
+      'Bad Request. Invalid query parameters (e.g., invalid count for random query).',
   })
   public async getSongList(
     @Query() query: PageQueryDTO,