feat(backend): add pagination and search to user endpoints

- Add pagination support to GET /users endpoint (limit, offset)
- Create new GET /users/search endpoint with filters (username, email, auth_type, role_id)
- Remove unused GET /users/role/:roleId endpoint
- Update response format to include pagination metadata
- Add pagination query schemas and validation helper
- Update unit tests for new paginated response structure

BREAKING CHANGE: GET /users response format changed from { success, data: [...] } to { success, data: { users: [...], pagination: {...} } }

Author: Lasim

services/backend/api-spec.json

@@ -1,11 +1,11 @@
 import type { FastifyInstance } from 'fastify';
 import listUsersRoute from './listUsers';
+import searchUsersRoute from './search';
 import getUserByIdRoute from './getUserById';
 import updateUserRoute from './updateUser';
 import deleteUserRoute from './deleteUser';
 import assignRoleRoute from './assignRole';
 import getUserStatsRoute from './getUserStats';
-import getUsersByRoleRoute from './getUsersByRole';
 import getCurrentUserRoute from './getCurrentUser';
 import getCurrentUserTeamsRoute from './getCurrentUserTeams';
 import deleteMyAccountRoute from './deleteMyAccount';
@@ -19,12 +19,12 @@ import metricsRoutes from './me/metrics';
 export default async function usersRoute(server: FastifyInstance) {
   // Register individual user route handlers
   await server.register(listUsersRoute);
+  await server.register(searchUsersRoute);
   await server.register(getUserByIdRoute);
   await server.register(updateUserRoute);
   await server.register(deleteUserRoute);
   await server.register(assignRoleRoute);
   await server.register(getUserStatsRoute);
-  await server.register(getUsersByRoleRoute);
   await server.register(getCurrentUserRoute);
   await server.register(getCurrentUserTeamsRoute);
   await server.register(deleteMyAccountRoute);

services/backend/api-spec.yaml

@@ -1,31 +1,40 @@
 import type { FastifyInstance } from 'fastify';
 import { UserService } from '../../services/userService';
 import { requirePermission } from '../../middleware/roleMiddleware';
-import { 
-  ERROR_RESPONSE_SCHEMA, 
-  USERS_LIST_RESPONSE_SCHEMA,
+import {
+  ERROR_RESPONSE_SCHEMA,
+  PAGINATION_QUERY_SCHEMA,
+  USERS_LIST_PAGINATED_RESPONSE_SCHEMA,
   type ErrorResponse,
-  type UsersListResponse,
-  type User
+  type UsersListPaginatedResponse,
+  type User,
+  type PaginationQuery,
+  validatePaginationParams
 } from './schemas';
 
 export default async function listUsersRoute(server: FastifyInstance) {
   const userService = new UserService();
 
-  // GET /users - List all users (admin only)
+  // GET /users - List all users (admin only) with pagination
   server.get('/users', {
     preValidation: requirePermission('users.list'),
     schema: {
       tags: ['Users'],
       summary: 'List all users',
-      description: 'Retrieves a list of all users in the system. Requires admin permissions.',
+      description: 'Retrieves a paginated list of all users in the system. Requires admin permissions. Supports pagination with limit (1-100, default: 20) and offset (default: 0) parameters.',
       security: [{ cookieAuth: [] }],
-      
+
+      querystring: PAGINATION_QUERY_SCHEMA,
+
       response: {
         200: {
-          ...USERS_LIST_RESPONSE_SCHEMA,
+          ...USERS_LIST_PAGINATED_RESPONSE_SCHEMA,
           description: 'Successfully retrieved users list'
         },
+        400: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Bad Request - Invalid pagination parameters'
+        },
         401: {
           ...ERROR_RESPONSE_SCHEMA,
           description: 'Unauthorized - Authentication required'
@@ -42,8 +51,12 @@ export default async function listUsersRoute(server: FastifyInstance) {
     },
   }, async (request, reply) => {
     try {
+      // Parse and validate pagination parameters
+      const query = request.query as PaginationQuery;
+      const { limit, offset } = validatePaginationParams(query);
+
       const users = await userService.getAllUsers();
-      
+
       // Convert users to proper response format following getCurrentUser pattern
       const serializedUsers: User[] = users.map(user => ({
         id: String(user.id),
@@ -60,14 +73,44 @@ export default async function listUsersRoute(server: FastifyInstance) {
           permissions: user.role.permissions
         } : undefined
       }));
-      
-      const successResponse: UsersListResponse = {
+
+      // Apply pagination
+      const total = serializedUsers.length;
+      const paginatedUsers = serializedUsers.slice(offset, offset + limit);
+
+      server.log.info({
+        operation: 'list_users',
+        totalResults: total,
+        returnedResults: paginatedUsers.length,
+        pagination: { limit, offset }
+      }, 'Users list completed');
+
+      const successResponse: UsersListPaginatedResponse = {
         success: true,
-        data: serializedUsers
+        data: {
+          users: paginatedUsers,
+          pagination: {
+            total,
+            limit,
+            offset,
+            has_more: offset + limit < total
+          }
+        }
       };
       const jsonString = JSON.stringify(successResponse);
       return reply.status(200).type('application/json').send(jsonString);
     } catch (error) {
+      // Check if it's a validation error
+      if (error instanceof Error && error.message.includes('must be')) {
+        server.log.warn({ error: error.message }, 'Invalid pagination parameters');
+        const errorResponse: ErrorResponse = {
+          success: false,
+          error: error.message
+        };
+        const jsonString = JSON.stringify(errorResponse);
+        return reply.status(400).type('application/json').send(jsonString);
+      }
+
       server.log.error(error, 'Error fetching users');
       const errorResponse: ErrorResponse = {
         success: false,

services/backend/src/routes/users/getUsersByRole.ts

@@ -222,11 +222,88 @@ export const ASSIGN_ROLE_REQUEST_SCHEMA = {
   additionalProperties: false
 } as const;
 
+// ===== PAGINATION SCHEMAS =====
+export const PAGINATION_QUERY_SCHEMA = {
+  type: 'object',
+  properties: {
+    limit: {
+      type: 'string',
+      pattern: '^\\d+$',
+      description: 'Maximum number of items to return (1-100, default: 20)'
+    },
+    offset: {
+      type: 'string',
+      pattern: '^\\d+$',
+      description: 'Number of items to skip (≥0, default: 0)'
+    }
+  },
+  additionalProperties: false
+} as const;
+
+const PAGINATION_SCHEMA = {
+  type: 'object',
+  properties: {
+    total: {
+      type: 'number',
+      description: 'Total number of users'
+    },
+    limit: {
+      type: 'number',
+      description: 'Number of users per page'
+    },
+    offset: {
+      type: 'number',
+      description: 'Number of users skipped'
+    },
+    has_more: {
+      type: 'boolean',
+      description: 'Whether there are more users beyond this page'
+    }
+  },
+  required: ['total', 'limit', 'offset', 'has_more']
+} as const;
+
+export const SEARCH_USERS_QUERY_SCHEMA = {
+  type: 'object',
+  properties: {
+    // Search filters (all optional)
+    username: {
+      type: 'string',
+      description: 'Filter by username (partial match, case-insensitive)'
+    },
+    email: {
+      type: 'string',
+      description: 'Filter by email (partial match, case-insensitive)'
+    },
+    auth_type: {
+      type: 'string',
+      enum: ['email', 'github'],
+      description: 'Filter by authentication type'
+    },
+    role_id: {
+      type: 'string',
+      description: 'Filter by role ID (exact match)'
+    },
+    // Pagination
+    limit: {
+      type: 'string',
+      pattern: '^\\d+$',
+      description: 'Maximum number of items to return (1-100, default: 20)'
+    },
+    offset: {
+      type: 'string',
+      pattern: '^\\d+$',
+      description: 'Number of items to skip (≥0, default: 0)'
+    }
+  },
+  additionalProperties: false
+} as const;
+
 // ===== RESPONSE SCHEMAS =====
 export const USERS_LIST_RESPONSE_SCHEMA = {
   type: 'object',
   properties: {
-    success: { 
+    success: {
       type: 'boolean',
       description: 'Indicates if the operation was successful'
     },
@@ -239,6 +316,29 @@ export const USERS_LIST_RESPONSE_SCHEMA = {
   required: ['success', 'data']
 } as const;
 
+export const USERS_LIST_PAGINATED_RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: {
+    success: {
+      type: 'boolean',
+      description: 'Indicates if the operation was successful'
+    },
+    data: {
+      type: 'object',
+      properties: {
+        users: {
+          type: 'array',
+          items: USER_SCHEMA,
+          description: 'Array of users for current page'
+        },
+        pagination: PAGINATION_SCHEMA
+      },
+      required: ['users', 'pagination']
+    }
+  },
+  required: ['success', 'data']
+} as const;
+
 export const USER_TEAMS_RESPONSE_SCHEMA = {
   type: 'object',
   properties: {
@@ -328,12 +428,55 @@ export interface AssignRoleRequest {
   role_id: string;
 }
 
+export interface PaginationQuery {
+  limit?: string;
+  offset?: string;
+}
+
+export interface SearchUsersQuery extends PaginationQuery {
+  username?: string;
+  email?: string;
+  auth_type?: 'email' | 'github';
+  role_id?: string;
+}
+
+export interface PaginationMetadata {
+  total: number;
+  limit: number;
+  offset: number;
+  has_more: boolean;
+}
+
 export interface UsersListResponse {
   success: boolean;
   data: User[];
 }
 
+export interface UsersListPaginatedResponse {
+  success: boolean;
+  data: {
+    users: User[];
+    pagination: PaginationMetadata;
+  };
+}
+
 export interface UserTeamsResponse {
   success: boolean;
   teams: TeamItem[];
 }
+
+// Validation helper function
+export function validatePaginationParams(query: PaginationQuery): { limit: number; offset: number } {
+  const limit = query.limit ? parseInt(query.limit, 10) : 20;
+  const offset = query.offset ? parseInt(query.offset, 10) : 0;
+
+  if (isNaN(limit) || limit < 1 || limit > 100) {
+    throw new Error('Limit must be between 1 and 100');
+  }
+
+  if (isNaN(offset) || offset < 0) {
+    throw new Error('Offset must be non-negative');
+  }
+
+  return { limit, offset };
+}