feat: Add pagination to list endpoints (closes #63)

- Add standard limit/offset pagination to GET /bounties, /milestones, /maintenance-pools, and /users
- Implement PaginationQueryDto with default page size of 50 and enforced maximum of 100
- Return paginated responses with metadata (page, limit, totalItems, totalPages, hasNextPage, hasPreviousPage)
- Add comprehensive e2e tests verifying pagination behavior across all four endpoints
- Ensure backward compatibility by making pagination parameters optional with sensible defaults
- Order results by createdAt DESC for consistent pagination

This resolves the unbounded query issue where list endpoints returned entire tables
in a single response, preventing performance degradation as the platform scales.

Author: senmalong

src/bounties/bounties.controller.ts

@@ -1,11 +1,14 @@
 import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiTags, ApiQuery } from '@nestjs/swagger';
 import { IsString } from 'class-validator';
 import { BountiesService } from './bounties.service';
 import { CreateBountyDto } from './dto/create-bounty.dto';
 import { ClaimBountyDto } from './dto/claim-bounty.dto';
 import { BountyStatus } from '../common/enums';
 import { Idempotent } from '../common/idempotency/idempotent.decorator';
+import { PaginationQueryDto } from '../common/dto/pagination-query.dto';
+import { PaginatedResponseDto } from '../common/dto/paginated-response.dto';
+import { Bounty } from '../common/entities';
 
 class FundBountyDto {
   @IsString()
@@ -23,8 +26,17 @@ export class BountiesController {
   }
 
   @Get()
-  list(@Query('status') status?: BountyStatus) {
-    return this.bountiesService.list(status);
+  @ApiQuery({ name: 'status', required: false, enum: BountyStatus })
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  async list(
+    @Query('status') status?: BountyStatus,
+    @Query() paginationQuery?: PaginationQueryDto,
+  ): Promise<PaginatedResponseDto<Bounty>> {
+    const page = paginationQuery?.page || 1;
+    const limit = paginationQuery?.limit || 50;
+    const { data, total } = await this.bountiesService.list(status, page, limit);
+    return new PaginatedResponseDto(data, page, limit, total);
   }
 
   @Get(':id')

src/bounties/bounties.service.ts

@@ -171,7 +171,21 @@ export class BountiesService {
     return overdue.length;
   }
 
-  async list(status?: BountyStatus): Promise<Bounty[]> {
-    return this.bountyRepo.find({ where: status ? { status } : {} });
+  async list(
+    status?: BountyStatus,
+    page: number = 1,
+    limit: number = 50,
+  ): Promise<{ data: Bounty[]; total: number }> {
+    const skip = (page - 1) * limit;
+    const where = status ? { status } : {};
+
+    const [data, total] = await this.bountyRepo.findAndCount({
+      where,
+      take: limit,
+      skip,
+      order: { createdAt: 'DESC' },
+    });
+
+    return { data, total };
   }
 }

src/common/dto/paginated-response.dto.ts

@@ -0,0 +1,54 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+/**
+ * Metadata for paginated responses, allowing clients to know if
+ * more pages exist and how to request them.
+ */
+export class PaginationMetadata {
+  @ApiProperty({ description: 'Current page number (1-indexed)' })
+  page: number;
+
+  @ApiProperty({ description: 'Number of items per page' })
+  limit: number;
+
+  @ApiProperty({ description: 'Total number of items across all pages' })
+  totalItems: number;
+
+  @ApiProperty({ description: 'Total number of pages' })
+  totalPages: number;
+
+  @ApiProperty({ description: 'Whether there is a next page' })
+  hasNextPage: boolean;
+
+  @ApiProperty({ description: 'Whether there is a previous page' })
+  hasPreviousPage: boolean;
+}
+
+/**
+ * Standard paginated response wrapper for list endpoints.
+ */
+export class PaginatedResponseDto<T> {
+  @ApiProperty({ description: 'Array of items for the current page' })
+  data: T[];
+
+  @ApiProperty({ description: 'Pagination metadata', type: PaginationMetadata })
+  meta: PaginationMetadata;
+
+  constructor(
+    data: T[],
+    page: number,
+    limit: number,
+    totalItems: number,
+  ) {
+    this.data = data;
+    const totalPages = Math.ceil(totalItems / limit);
+    this.meta = {
+      page,
+      limit,
+      totalItems,
+      totalPages,
+      hasNextPage: page < totalPages,
+      hasPreviousPage: page > 1,
+    };
+  }
+}

src/common/dto/pagination-query.dto.ts

@@ -0,0 +1,33 @@
+import { IsInt, IsOptional, Min, Max } from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+/**
+ * Standard pagination query parameters for list endpoints.
+ * Enforces a maximum page size to prevent unbounded responses.
+ */
+export class PaginationQueryDto {
+  @ApiPropertyOptional({
+    description: 'Page number (1-indexed)',
+    default: 1,
+    minimum: 1,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @ApiPropertyOptional({
+    description: 'Number of items per page',
+    default: 50,
+    minimum: 1,
+    maximum: 100,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 50;
+}

src/maintenance-pool/maintenance-pool.controller.ts

@@ -1,10 +1,13 @@
-import { Body, Controller, Get, Param, Post } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
+import { ApiTags, ApiQuery } from '@nestjs/swagger';
 import { IsOptional, IsString, IsUUID } from 'class-validator';
 import { MaintenancePoolService } from './maintenance-pool.service';
 import { CreatePoolDto } from './dto/create-pool.dto';
 import { IsMoneyAmount } from '../common/validators/money.validator';
 import { Idempotent } from '../common/idempotency/idempotent.decorator';
+import { PaginationQueryDto } from '../common/dto/pagination-query.dto';
+import { PaginatedResponseDto } from '../common/dto/paginated-response.dto';
+import { MaintenancePool } from '../common/entities';
 
 class DepositDto {
   @IsMoneyAmount()
@@ -37,8 +40,15 @@ export class MaintenancePoolController {
   }
 
   @Get()
-  list() {
-    return this.poolService.list();
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  async list(
+    @Query() paginationQuery?: PaginationQueryDto,
+  ): Promise<PaginatedResponseDto<MaintenancePool>> {
+    const page = paginationQuery?.page || 1;
+    const limit = paginationQuery?.limit || 50;
+    const { data, total } = await this.poolService.list(page, limit);
+    return new PaginatedResponseDto(data, page, limit, total);
   }
 
   @Get(':id')

src/maintenance-pool/maintenance-pool.service.ts

@@ -106,7 +106,18 @@ export class MaintenancePoolService {
     return payment;
   }
 
-  async list(): Promise<MaintenancePool[]> {
-    return this.poolRepo.find();
+  async list(
+    page: number = 1,
+    limit: number = 50,
+  ): Promise<{ data: MaintenancePool[]; total: number }> {
+    const skip = (page - 1) * limit;
+
+    const [data, total] = await this.poolRepo.findAndCount({
+      take: limit,
+      skip,
+      order: { createdAt: 'DESC' },
+    });
+
+    return { data, total };
   }
 }

src/milestones/milestones.controller.ts

@@ -1,9 +1,12 @@
-import { Body, Controller, Get, Param, Post } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
+import { ApiTags, ApiQuery } from '@nestjs/swagger';
 import { IsOptional, IsString, IsUUID } from 'class-validator';
 import { MilestonesService } from './milestones.service';
 import { CreateMilestoneDto } from './dto/create-milestone.dto';
 import { Idempotent } from '../common/idempotency/idempotent.decorator';
+import { PaginationQueryDto } from '../common/dto/pagination-query.dto';
+import { PaginatedResponseDto } from '../common/dto/paginated-response.dto';
+import { Milestone } from '../common/entities';
 
 class FundMilestoneDto {
   @IsString()
@@ -30,8 +33,15 @@ export class MilestonesController {
   }
 
   @Get()
-  list() {
-    return this.milestonesService.list();
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  async list(
+    @Query() paginationQuery?: PaginationQueryDto,
+  ): Promise<PaginatedResponseDto<Milestone>> {
+    const page = paginationQuery?.page || 1;
+    const limit = paginationQuery?.limit || 50;
+    const { data, total } = await this.milestonesService.list(page, limit);
+    return new PaginatedResponseDto(data, page, limit, total);
   }
 
   @Get(':id')

src/milestones/milestones.service.ts

@@ -128,7 +128,18 @@ export class MilestonesService {
     return payment;
   }
 
-  async list(): Promise<Milestone[]> {
-    return this.milestoneRepo.find();
+  async list(
+    page: number = 1,
+    limit: number = 50,
+  ): Promise<{ data: Milestone[]; total: number }> {
+    const skip = (page - 1) * limit;
+
+    const [data, total] = await this.milestoneRepo.findAndCount({
+      take: limit,
+      skip,
+      order: { createdAt: 'DESC' },
+    });
+
+    return { data, total };
   }
 }

src/users/users.controller.ts

@@ -1,8 +1,11 @@
-import { Body, Controller, Get, Param, Patch, UseGuards } from '@nestjs/common';
-import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Get, Param, Patch, Query, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags, ApiQuery } from '@nestjs/swagger';
 import { IsString } from 'class-validator';
 import { UsersService } from './users.service';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { PaginationQueryDto } from '../common/dto/pagination-query.dto';
+import { PaginatedResponseDto } from '../common/dto/paginated-response.dto';
+import { User } from '../common/entities';
 
 class SetStellarAddressDto {
   @IsString()
@@ -15,8 +18,15 @@ export class UsersController {
   constructor(private readonly usersService: UsersService) {}
 
   @Get()
-  list() {
-    return this.usersService.list();
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  async list(
+    @Query() paginationQuery?: PaginationQueryDto,
+  ): Promise<PaginatedResponseDto<User>> {
+    const page = paginationQuery?.page || 1;
+    const limit = paginationQuery?.limit || 50;
+    const { data, total } = await this.usersService.list(page, limit);
+    return new PaginatedResponseDto(data, page, limit, total);
   }
 
   @Get(':id')

src/users/users.service.ts

@@ -98,7 +98,18 @@ export class UsersService {
     return this.userRepo.save(user);
   }
 
-  async list(): Promise<User[]> {
-    return this.userRepo.find();
+  async list(
+    page: number = 1,
+    limit: number = 50,
+  ): Promise<{ data: User[]; total: number }> {
+    const skip = (page - 1) * limit;
+
+    const [data, total] = await this.userRepo.findAndCount({
+      take: limit,
+      skip,
+      order: { createdAt: 'DESC' },
+    });
+
+    return { data, total };
   }
 }