Merge pull request #439 from favourawaku/staging

  This PR addresses four connected issues to improve the payments and limits endpoints

Author: Jambox11

src/common/dto/pagination.dto.ts

@@ -0,0 +1,35 @@
+import { IsInt, IsOptional, Min, Max } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+
+export class PaginationDto {
+  @ApiProperty({
+    example: 1,
+    description: 'Page number (starting from 1)',
+    required: false,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: 'page must be an integer' })
+  @Min(1, { message: 'page must be at least 1' })
+  page: number = 1;
+
+  @ApiProperty({
+    example: 20,
+    description: 'Number of items per page (max 100)',
+    required: false,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: 'limit must be an integer' })
+  @Min(1, { message: 'limit must be at least 1' })
+  @Max(100, { message: 'limit must not exceed 100' })
+  limit: number = 20;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  total: number;
+  page: number;
+  limit: number;
+}

src/limits/dto/create-limit.dto.ts

@@ -8,6 +8,7 @@ import {
   IsBoolean,
   MaxLength,
 } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
 
 export enum LimitPeriod {
   DAILY = 'DAILY',
@@ -16,27 +17,55 @@ export enum LimitPeriod {
 }
 
 export class CreateLimitDto {
-  @IsUUID()
+  @ApiProperty({
+    example: '123e4567-e89b-12d3-a456-426614174000',
+    description: 'User ID (UUID)',
+  })
+  @IsUUID(undefined, { message: 'userId must be a valid UUID' })
   userId: string;
 
-  @IsNumber({ maxDecimalPlaces: 8 })
-  @IsPositive()
+  @ApiProperty({
+    example: 1000.12345678,
+    description: 'Per-transaction limit (max 8 decimal places) - must be positive',
+  })
+  @IsNumber({ maxDecimalPlaces: 8 }, { message: 'perTransactionLimit must be a number with max 8 decimal places' })
+  @IsPositive({ message: 'perTransactionLimit must be positive' })
   perTransactionLimit: number;
 
-  @IsNumber({ maxDecimalPlaces: 8 })
-  @IsPositive()
+  @ApiProperty({
+    example: 10000.5,
+    description: 'Period limit amount (max 8 decimal places) - must be positive',
+  })
+  @IsNumber({ maxDecimalPlaces: 8 }, { message: 'periodLimit must be a number with max 8 decimal places' })
+  @IsPositive({ message: 'periodLimit must be positive' })
   periodLimit: number;
 
-  @IsEnum(LimitPeriod)
+  @ApiProperty({
+    example: 'DAILY',
+    enum: LimitPeriod,
+    description: 'Limit period',
+    required: false,
+  })
+  @IsEnum(LimitPeriod, { message: 'period must be one of: DAILY, WEEKLY, MONTHLY' })
   @IsOptional()
   period?: LimitPeriod;
 
-  @IsString()
-  @MaxLength(12)
+  @ApiProperty({
+    example: 'USD',
+    description: 'Asset code (max 12 characters)',
+    required: false,
+  })
+  @IsString({ message: 'assetCode must be a string' })
+  @MaxLength(12, { message: 'assetCode must not exceed 12 characters' })
   @IsOptional()
   assetCode?: string;
 
-  @IsBoolean()
+  @ApiProperty({
+    example: true,
+    description: 'Whether the limit is active',
+    required: false,
+  })
+  @IsBoolean({ message: 'isActive must be a boolean' })
   @IsOptional()
   isActive?: boolean;
 }

src/limits/dto/limits-filter.dto.ts

@@ -0,0 +1,26 @@
+import { IsEnum, IsOptional, IsBoolean } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { LimitPeriod } from './create-limit.dto';
+import { Type } from 'class-transformer';
+
+export class LimitsFilterDto {
+  @ApiProperty({
+    example: 'DAILY',
+    enum: LimitPeriod,
+    description: 'Filter by limit period',
+    required: false,
+  })
+  @IsEnum(LimitPeriod, { message: 'period must be one of: DAILY, WEEKLY, MONTHLY' })
+  @IsOptional()
+  period?: LimitPeriod;
+
+  @ApiProperty({
+    example: true,
+    description: 'Filter by active status',
+    required: false,
+  })
+  @IsBoolean({ message: 'isActive must be a boolean' })
+  @IsOptional()
+  @Type(() => Boolean)
+  isActive?: boolean;
+}

src/limits/dto/set-limits.dto.ts

@@ -0,0 +1,20 @@
+import { IsNumber, IsPositive } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class SetLimitsDto {
+  @ApiProperty({
+    example: 5000,
+    description: 'Daily transaction limit amount - must be positive',
+  })
+  @IsNumber({}, { message: 'dailyLimit must be a number' })
+  @IsPositive({ message: 'dailyLimit must be positive' })
+  dailyLimit: number;
+
+  @ApiProperty({
+    example: 1000,
+    description: 'Per-transaction limit amount - must be positive',
+  })
+  @IsNumber({}, { message: 'perTransactionLimit must be a number' })
+  @IsPositive({ message: 'perTransactionLimit must be positive' })
+  perTransactionLimit: number;
+}

src/limits/dto/update-limit.dto.ts

@@ -2,3 +2,4 @@ import { PartialType } from '@nestjs/mapped-types';
 import { CreateLimitDto } from './create-limit.dto';
 
 export class UpdateLimitDto extends PartialType(CreateLimitDto) {}
+

src/limits/limits.controller.spec.ts

@@ -58,4 +58,21 @@ describe('LimitsController', () => {
     await controller.removeLimits(walletId);
     expect(limitsService.removeLimits).toHaveBeenCalledWith(walletId);
   });
+
+  describe('swagger decorators', () => {
+    it('should have @ApiResponse decorators on all routes', () => {
+      const routes = ['setLimits', 'getLimits', 'removeLimits'];
+
+      routes.forEach((route) => {
+        const descriptor = Object.getOwnPropertyDescriptor(
+          LimitsController.prototype,
+          route,
+        );
+        expect(descriptor).toBeDefined();
+
+        const metadata = Reflect.getMetadata('swagger/apiResponse', descriptor.value);
+        expect(metadata).toBeDefined();
+      });
+    });
+  });
 });

src/limits/limits.controller.ts

@@ -8,23 +8,67 @@ import {
   HttpCode,
   HttpStatus,
 } from '@nestjs/common';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiBody,
+  ApiParam,
+} from '@nestjs/swagger';
 import { LimitsService } from './limits.service';
-import { IsNumber, IsPositive } from 'class-validator';
-
-class SetLimitsDto {
-  @IsNumber()
-  @IsPositive()
-  dailyLimit: number;
-
-  @IsNumber()
-  @IsPositive()
-  perTransactionLimit: number;
-}
+import { SetLimitsDto } from './dto/set-limits.dto';
 
+@ApiTags('limits')
 @Controller('wallets/:walletId/limits')
 export class LimitsController {
   constructor(private readonly limitsService: LimitsService) {}
 
+  @ApiOperation({ summary: 'Set wallet transaction and daily limits' })
+  @ApiParam({ name: 'walletId', description: 'Wallet ID' })
+  @ApiBody({
+    type: SetLimitsDto,
+    examples: {
+      default: {
+        value: {
+          dailyLimit: 5000,
+          perTransactionLimit: 1000,
+        },
+      },
+    },
+  })
+  @ApiResponse({
+    status: 201,
+    description: 'Limits set successfully',
+    example: {
+      walletId: '123e4567-e89b-12d3-a456-426614174000',
+      dailyLimit: 5000,
+      perTransactionLimit: 1000,
+    },
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Bad request - invalid input',
+    example: {
+      statusCode: 400,
+      timestamp: '2024-06-24T12:34:56.789Z',
+      path: '/wallets/123/limits',
+      method: 'POST',
+      message: ['dailyLimit must be positive'],
+      error: 'Bad Request',
+    },
+  })
+  @ApiResponse({
+    status: 404,
+    description: 'Wallet not found',
+    example: {
+      statusCode: 404,
+      timestamp: '2024-06-24T12:34:56.789Z',
+      path: '/wallets/invalid/limits',
+      method: 'POST',
+      message: 'Wallet not found',
+      error: 'Not Found',
+    },
+  })
   @Post()
   setLimits(@Param('walletId') walletId: string, @Body() dto: SetLimitsDto) {
     return this.limitsService.setLimits(
@@ -34,11 +78,52 @@ export class LimitsController {
     );
   }
 
+  @ApiOperation({ summary: 'Get wallet limits' })
+  @ApiParam({ name: 'walletId', description: 'Wallet ID' })
+  @ApiResponse({
+    status: 200,
+    description: 'Wallet limits retrieved successfully',
+    example: {
+      walletId: '123e4567-e89b-12d3-a456-426614174000',
+      dailyLimit: 5000,
+      perTransactionLimit: 1000,
+    },
+  })
+  @ApiResponse({
+    status: 404,
+    description: 'No limits found for wallet',
+    example: {
+      statusCode: 404,
+      timestamp: '2024-06-24T12:34:56.789Z',
+      path: '/wallets/123/limits',
+      method: 'GET',
+      message: 'No limits found for wallet',
+      error: 'Not Found',
+    },
+  })
   @Get()
   getLimits(@Param('walletId') walletId: string) {
     return this.limitsService.getLimits(walletId);
   }
 
+  @ApiOperation({ summary: 'Remove wallet limits' })
+  @ApiParam({ name: 'walletId', description: 'Wallet ID' })
+  @ApiResponse({
+    status: 204,
+    description: 'Limits removed successfully',
+  })
+  @ApiResponse({
+    status: 404,
+    description: 'No limits found for wallet',
+    example: {
+      statusCode: 404,
+      timestamp: '2024-06-24T12:34:56.789Z',
+      path: '/wallets/123/limits',
+      method: 'DELETE',
+      message: 'No limits found for wallet 123',
+      error: 'Not Found',
+    },
+  })
   @Delete()
   @HttpCode(HttpStatus.NO_CONTENT)
   removeLimits(@Param('walletId') walletId: string) {

src/payments/dto/create-payment.dto.ts

@@ -5,36 +5,71 @@ import {
   IsPositive,
   IsOptional,
   IsInt,
+  Min,
 } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
 
 export class CreatePaymentDto {
   /** Sender wallet UUID — validated to exist and be ACTIVE before payment is created. */
-  @IsString()
-  @IsNotEmpty()
+  @ApiProperty({
+    example: '123e4567-e89b-12d3-a456-426614174000',
+    description: 'Sender wallet UUID - must exist and be ACTIVE',
+  })
+  @IsString({ message: 'walletId must be a string' })
+  @IsNotEmpty({ message: 'walletId is required' })
   walletId: string;
 
   /** Receiver wallet UUID — validated to exist before payment is created. */
-  @IsString()
-  @IsNotEmpty()
+  @ApiProperty({
+    example: '123e4567-e89b-12d3-a456-426614174001',
+    description: 'Receiver wallet UUID - must exist',
+  })
+  @IsString({ message: 'receiverWalletId must be a string' })
+  @IsNotEmpty({ message: 'receiverWalletId is required' })
   receiverWalletId: string;
 
-  @IsNumber()
-  @IsPositive()
+  @ApiProperty({
+    example: 100.5,
+    description: 'Payment amount - must be positive',
+  })
+  @IsNumber({}, { message: 'amount must be a number' })
+  @IsPositive({ message: 'amount must be positive' })
   amount: number;
 
-  @IsString()
-  @IsNotEmpty()
+  @ApiProperty({
+    example: 'USD',
+    description: 'Currency code',
+  })
+  @IsString({ message: 'currency must be a string' })
+  @IsNotEmpty({ message: 'currency is required' })
   currency: string;
 
-  @IsString()
+  @ApiProperty({
+    example: 'Payment for services',
+    description: 'Optional payment description',
+    required: false,
+  })
+  @IsString({ message: 'description must be a string' })
   @IsOptional()
   description?: string;
 
   /** Legacy sender ID (LegacyUser.id) — required for payment record FK. */
-  @IsInt()
+  @ApiProperty({
+    example: 1,
+    description: 'Legacy sender ID (LegacyUser.id)',
+  })
+  @IsInt({ message: 'fromId must be an integer' })
+  @IsNotEmpty({ message: 'fromId is required' })
+  @Min(1, { message: 'fromId must be greater than 0' })
   fromId: number;
 
   /** Legacy receiver ID (LegacyUser.id) — required for payment record FK. */
-  @IsInt()
+  @ApiProperty({
+    example: 2,
+    description: 'Legacy receiver ID (LegacyUser.id)',
+  })
+  @IsInt({ message: 'toId must be an integer' })
+  @IsNotEmpty({ message: 'toId is required' })
+  @Min(1, { message: 'toId must be greater than 0' })
   toId: number;
 }