Merge pull request #296 from BigBen-7/feat/be-34-36-37-39-tests-swagger-export

[BE-34/36/37/39] Unit tests, e2e tests, Swagger decorators, document export

Author: mftee

backend/src/auth/auth.controller.ts

@@ -1,4 +1,4 @@
-import {
+import {
   Body,
   Controller,
   Post,
@@ -8,6 +8,7 @@
   UseGuards,
   BadRequestException,
 } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
 import { ConfigService } from '@nestjs/config';
 import { AuthGuard } from '@nestjs/passport';
 import { Request, Response } from 'express';
@@ -19,6 +20,7 @@ import { RegisterAuthDto } from './dto/register-auth.dto';
 import { LoginAuthDto } from './dto/login-auth.dto';
 import { RefreshAuthDto } from './dto/refresh-auth.dto';
 
+@ApiTags('Authentication')
 @Controller('auth')
 export class AuthController {
   constructor(
@@ -27,28 +29,41 @@ export class AuthController {
   ) {}
 
   @Post('register')
+  @ApiOperation({ summary: 'Register a new user' })
+  @ApiResponse({ status: 201, description: 'User registered successfully' })
+  @ApiResponse({ status: 409, description: 'Email already in use' })
   register(@Body() dto: RegisterAuthDto) {
     return this.authService.register(dto);
   }
 
   @Post('login')
+  @ApiOperation({ summary: 'Login with email and password' })
+  @ApiResponse({ status: 200, description: 'Returns access and refresh tokens' })
+  @ApiResponse({ status: 401, description: 'Invalid credentials' })
   login(@Body() dto: LoginAuthDto) {
     return this.authService.login(dto);
   }
 
   @Post('refresh')
+  @ApiOperation({ summary: 'Refresh access token' })
+  @ApiResponse({ status: 200, description: 'Returns a new access token' })
+  @ApiResponse({ status: 401, description: 'Invalid or expired refresh token' })
   refresh(@Body() dto: RefreshAuthDto) {
     return this.authService.refreshToken(dto);
   }
 
   @Get('google')
   @UseGuards(AuthGuard('google'))
+  @ApiOperation({ summary: 'Initiate Google OAuth login' })
+  @ApiResponse({ status: 302, description: 'Redirects to Google login' })
   googleAuth() {
     return;
   }
 
   @Get('google/callback')
   @UseGuards(AuthGuard('google'))
+  @ApiOperation({ summary: 'Google OAuth callback' })
+  @ApiResponse({ status: 302, description: 'Redirects to frontend with token' })
   async googleAuthRedirect(
     @Req() req: Request & { user?: GoogleProfile },
     @Res() res: Response,
@@ -77,20 +92,24 @@ export class AuthController {
 
   @Get('github')
   @UseGuards(AuthGuard('github'))
+  @ApiOperation({ summary: 'Initiate GitHub OAuth login' })
+  @ApiResponse({ status: 302, description: 'Redirects to GitHub login' })
   githubAuth() {
     return;
   }
 
   @Get('github/callback')
   @UseGuards(AuthGuard('github'))
+  @ApiOperation({ summary: 'GitHub OAuth callback' })
+  @ApiResponse({ status: 302, description: 'Redirects to frontend with token' })
   async githubAuthRedirect(
     @Req() req: Request & { user?: GithubProfile },
     @Res() res: Response,
   ) {
     const profile = req.user;
     const githubId = profile?.id?.toString();
     const email = profile?.emails?.[0]?.value;
-    const identifier = email || (githubId ? github: : null);
+    const identifier = email || (githubId ? `github:${githubId}` : null);
     if (!identifier) {
       throw new BadRequestException('GitHub profile could not be identified');
     }

backend/src/auth/dto/login-auth.dto.ts

@@ -1,9 +1,12 @@
-import { IsEmail, IsNotEmpty } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty } from 'class-validator';
 
 export class LoginAuthDto {
+  @ApiProperty({ example: 'user@example.com' })
   @IsEmail()
   email: string;
 
+  @ApiProperty({ example: 'password123' })
   @IsNotEmpty()
   password: string;
 }

backend/src/auth/dto/refresh-auth.dto.ts

@@ -1,6 +1,8 @@
-import { IsNotEmpty } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty } from 'class-validator';
 
 export class RefreshAuthDto {
+  @ApiProperty({ description: 'JWT refresh token' })
   @IsNotEmpty()
   refreshToken: string;
 }

backend/src/auth/dto/register-auth.dto.ts

@@ -1,13 +1,17 @@
-import { IsEmail, IsNotEmpty, MinLength } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty, MinLength } from 'class-validator';
 
 export class RegisterAuthDto {
+  @ApiProperty({ example: 'user@example.com' })
   @IsEmail()
   email: string;
 
+  @ApiProperty({ example: 'password123', minLength: 6 })
   @IsNotEmpty()
   @MinLength(6)
   password: string;
 
+  @ApiProperty({ example: 'Jane Doe' })
   @IsNotEmpty()
   fullName: string;
 }

backend/src/documents/documents.controller.ts

@@ -2,6 +2,7 @@ import {
   BadRequestException,
   ConflictException,
   Controller,
+  ForbiddenException,
   Get,
   NotFoundException,
   Param,
@@ -15,11 +16,14 @@ import {
 } from '@nestjs/common';
 import { FileInterceptor } from '@nestjs/platform-express';
 import { ConfigService } from '@nestjs/config';
+import { ApiBearerAuth, ApiConsumes, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { Request, Response } from 'express';
 import { createHash } from 'crypto';
 import { promises as fs } from 'fs';
 import { extname, join } from 'path';
 import * as multer from 'multer';
+import * as PDFDocument from 'pdfkit';
+import * as ExcelJS from 'exceljs';
 
 import { DocumentsService } from './documents.service';
 import { DocumentStatus } from './entities/document.entity';
@@ -38,10 +42,11 @@ const fileFilter: multer.FileFilterCallback = (_req, file, callback) => {
   if (ALLOWED_MIME_TYPES.includes(file.mimetype)) {
     return callback(null, true);
   }
-
   return callback(new BadRequestException('Only PDF, PNG, or JPEG files are allowed'), false);
 };
 
+@ApiTags('Documents')
+@ApiBearerAuth('JWT-auth')
 @Controller('documents')
 export class DocumentsController {
   constructor(
@@ -68,38 +73,31 @@ export class DocumentsController {
 
   @Post('upload')
   @UseGuards(JwtAuthGuard)
-  @UseInterceptors(
-    FileInterceptor('file', {
-      storage: multerStorage,
-      fileFilter,
-      limits: { fileSize: MAX_FILE_SIZE_BYTES },
-    }),
-  )
+  @UseInterceptors(FileInterceptor('file', { storage: multerStorage, fileFilter, limits: { fileSize: MAX_FILE_SIZE_BYTES } }))
+  @ApiOperation({ summary: 'Upload a document for analysis' })
+  @ApiConsumes('multipart/form-data')
+  @ApiResponse({ status: 202, description: 'Document accepted for processing' })
+  @ApiResponse({ status: 200, description: 'Document already exists (duplicate)' })
+  @ApiResponse({ status: 400, description: 'Invalid file type or missing file' })
+  @ApiResponse({ status: 401, description: 'Unauthenticated' })
   async uploadDocument(
     @UploadedFile() file: Express.Multer.File,
     @Req() req: Request & { user?: User },
     @Res() res: Response,
   ) {
-    if (!file) {
-      throw new BadRequestException('File is required');
-    }
+    if (!file) throw new BadRequestException('File is required');
 
     const user = req.user;
-    if (!user) {
-      throw new BadRequestException('Authenticated user is required');
-    }
+    if (!user) throw new BadRequestException('Authenticated user is required');
 
     const fileHash = createHash('sha256').update(file.buffer).digest('hex');
     const existing = await this.documentsService.findByFileHash(fileHash);
-    if (existing) {
-      return res.status(200).send(existing);
-    }
+    if (existing) return res.status(200).send(existing);
 
     const uploadDir = this.configService.get<string>('UPLOAD_DIR') || './uploads';
     await fs.mkdir(uploadDir, { recursive: true });
 
-    const extension = extname(file.originalname) || '';
-    const filename = `${fileHash}${extension}`;
+    const filename = `${fileHash}${extname(file.originalname) || ''}`;
     const targetPath = join(uploadDir, filename);
     await fs.writeFile(targetPath, file.buffer);
 
@@ -117,39 +115,101 @@ export class DocumentsController {
     return res.status(202).send(document);
   }
 
+  // BE-39: Excel export — static route must come before dynamic :id routes
+  @Get('export/excel')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Export all user documents as Excel (.xlsx)' })
+  @ApiResponse({ status: 200, description: 'Excel file download' })
+  async exportExcel(@Req() req: Request & { user?: User }, @Res() res: Response) {
+    const documents = await this.documentsService.findByOwner(req.user!.id);
+
+    const workbook = new ExcelJS.Workbook();
+    const sheet = workbook.addWorksheet('Documents');
+    sheet.columns = [
+      { header: 'ID', key: 'id', width: 36 },
+      { header: 'Title', key: 'title', width: 30 },
+      { header: 'Status', key: 'status', width: 12 },
+      { header: 'Risk Score', key: 'riskScore', width: 12 },
+      { header: 'Risk Flags', key: 'riskFlags', width: 40 },
+      { header: 'Uploaded At', key: 'createdAt', width: 24 },
+    ];
+    documents.forEach((doc) =>
+      sheet.addRow({
+        ...doc,
+        riskFlags: doc.riskFlags?.join(', ') ?? '',
+      }),
+    );
+
+    res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
+    res.setHeader('Content-Disposition', 'attachment; filename="documents.xlsx"');
+    await workbook.xlsx.write(res);
+    res.end();
+  }
+
   @Post(':id/verify')
   @UseGuards(JwtAuthGuard)
-  async verifyDocument(@Param('id') id: string, @Res() res: Response) {
+  @ApiOperation({ summary: 'Queue a document for Stellar blockchain verification' })
+  @ApiResponse({ status: 202, description: 'Verification queued' })
+  @ApiResponse({ status: 403, description: 'Not the document owner' })
+  @ApiResponse({ status: 404, description: 'Document not found' })
+  @ApiResponse({ status: 409, description: 'Already verified' })
+  async verifyDocument(
+    @Param('id') id: string,
+    @Req() req: Request & { user?: User },
+    @Res() res: Response,
+  ) {
     const document = await this.documentsService.findById(id);
-    if (!document) {
-      throw new NotFoundException('Document not found');
-    }
-
-    if (document.status === DocumentStatus.VERIFIED) {
-      throw new ConflictException('Document has already been verified');
-    }
+    if (!document) throw new NotFoundException('Document not found');
+    if (document.ownerId !== req.user?.id) throw new ForbiddenException('Access denied');
+    if (document.status === DocumentStatus.VERIFIED) throw new ConflictException('Document has already been verified');
 
     await this.queueService.enqueueAnchor(document.id);
-
-    return res.status(202).json({
-      message: 'Verification queued',
-      documentId: document.id,
-    });
+    return res.status(202).json({ message: 'Verification queued', documentId: document.id });
   }
 
   @Get(':id/verification')
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get the latest verification record for a document' })
+  @ApiResponse({ status: 200, description: 'Verification record' })
+  @ApiResponse({ status: 404, description: 'Document or record not found' })
   async getVerification(@Param('id') id: string) {
     const document = await this.documentsService.findById(id);
-    if (!document) {
-      throw new NotFoundException('Document not found');
-    }
+    if (!document) throw new NotFoundException('Document not found');
 
     const record = await this.verificationService.findLatestByDocument(id);
-    if (!record) {
-      throw new NotFoundException('No verification record found for this document');
-    }
+    if (!record) throw new NotFoundException('No verification record found for this document');
 
     return record;
   }
+
+  // BE-39: PDF export
+  @Get(':id/export/pdf')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Export a single document report as PDF' })
+  @ApiResponse({ status: 200, description: 'PDF file download' })
+  @ApiResponse({ status: 404, description: 'Document not found' })
+  async exportPdf(@Param('id') id: string, @Res() res: Response) {
+    const document = await this.documentsService.findById(id);
+    if (!document) throw new NotFoundException('Document not found');
+
+    const verification = await this.verificationService.findLatestByDocument(id);
+
+    const doc = new PDFDocument({ margin: 50 });
+    res.setHeader('Content-Type', 'application/pdf');
+    res.setHeader('Content-Disposition', `attachment; filename="${document.title}.pdf"`);
+    doc.pipe(res);
+
+    doc.fontSize(18).text('Document Report', { align: 'center' }).moveDown();
+    doc.fontSize(12)
+      .text(`Title: ${document.title}`)
+      .text(`Uploaded: ${document.createdAt.toISOString()}`)
+      .text(`Status: ${document.status}`)
+      .text(`Risk Score: ${document.riskScore ?? 'N/A'}`)
+      .text(`Risk Flags: ${document.riskFlags?.join(', ') || 'None'}`)
+      .moveDown()
+      .text(`Stellar Tx Hash: ${verification?.stellarTxHash ?? 'Not anchored'}`)
+      .text(`Stellar Ledger: ${verification?.stellarLedger ?? 'N/A'}`);
+
+    doc.end();
+  }
 }

backend/src/risk-assessment/risk-assessment.controller.ts

@@ -1,14 +1,20 @@
-import { Controller, Get, Param, UseGuards } from '@nestjs/common';
+import { Controller, Get, Param, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 
 import { RiskAssessmentService } from './risk-assessment.service';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 
+@ApiTags('Documents')
+@ApiBearerAuth('JWT-auth')
 @Controller('documents')
 export class RiskAssessmentController {
   constructor(private readonly riskService: RiskAssessmentService) {}
 
   @Get(':id/risk')
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get risk assessment for a document' })
+  @ApiResponse({ status: 200, description: 'Risk score and flags' })
+  @ApiResponse({ status: 404, description: 'Document not found' })
   async getRisk(@Param('id') id: string) {
     return this.riskService.assessDocument(id);
   }