Refactor team member management routes to improve schema validation and error handling

- Updated removeTeamMemberRoute to use constant schemas for request parameters and responses.
- Enhanced transferOwnershipRoute with improved request body validation and error responses.
- Refactored updateMemberRoleRoute to utilize TypeScript interfaces for better type safety and validation.
- Consolidated team schemas in schemas.ts for consistency and clarity, replacing Zod with JSON Schema-like structures.
- Improved updateTeamRoute to handle errors more gracefully and ensure proper type assertions.

Author: Lasim

services/backend/api-spec.json

@@ -1,85 +1,120 @@
-import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
-import { ZodError } from 'zod';
-import { createSchema } from 'zod-openapi';
+import type { FastifyInstance } from 'fastify';
 import { TeamService } from '../../services/teamService';
 import { requirePermission } from '../../middleware/roleMiddleware';
-import { CreateTeamSchema, TeamResponseSchema, ErrorResponseSchema, type CreateTeamInput } from './schemas';
+import {
+  CREATE_TEAM_REQUEST_SCHEMA,
+  TEAM_SUCCESS_RESPONSE_SCHEMA,
+  ERROR_RESPONSE_SCHEMA,
+  type CreateTeamRequest,
+  type TeamSuccessResponse,
+  type ErrorResponse
+} from './schemas';
 
-export default async function createTeamRoute(fastify: FastifyInstance) {
+export default async function createTeamRoute(server: FastifyInstance) {
   // POST /teams - Create a new team
-  fastify.post<{ Body: CreateTeamInput }>('/teams', {
+  server.post('/teams', {
+    preValidation: requirePermission('teams.create'),
     schema: {
       tags: ['Teams'],
       summary: 'Create new team',
-      description: 'Creates a new team with the specified name and description. Users can create up to 3 teams maximum. The slug is automatically generated from the team name and made unique.',
+      description: 'Creates a new team with the specified name and description. Users can create up to 3 teams maximum. The slug is automatically generated from the team name and made unique. Requires Content-Type: application/json header when sending request body.',
       security: [{ cookieAuth: [] }],
-      body: createSchema(CreateTeamSchema),
+      
+      // Fastify validation schema
+      body: CREATE_TEAM_REQUEST_SCHEMA,
+      
+      // OpenAPI documentation (same schema, reused)
+      requestBody: {
+        required: true,
+        content: {
+          'application/json': {
+            schema: CREATE_TEAM_REQUEST_SCHEMA
+          }
+        }
+      },
+      
       response: {
-        201: createSchema(TeamResponseSchema.describe('Team created successfully')),
-        400: createSchema(ErrorResponseSchema.describe('Bad Request - Validation error or team limit reached')),
-        401: createSchema(ErrorResponseSchema.describe('Unauthorized - Authentication required')),
-        403: createSchema(ErrorResponseSchema.describe('Forbidden - Insufficient permissions')),
-        500: createSchema(ErrorResponseSchema.describe('Internal Server Error'))
+        201: {
+          ...TEAM_SUCCESS_RESPONSE_SCHEMA,
+          description: 'Team created successfully'
+        },
+        400: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Bad Request - Validation error or team limit reached'
+        },
+        401: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Unauthorized - Authentication required'
+        },
+        403: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Forbidden - Insufficient permissions'
+        },
+        500: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Internal Server Error'
+        }
       }
     },
-    preValidation: requirePermission('teams.create'),
-  }, async (request: FastifyRequest<{ Body: CreateTeamInput }>, reply: FastifyReply) => {
+  }, async (request, reply) => {
     try {
       if (!request.user) {
-        return reply.status(401).send({
+        const errorResponse: ErrorResponse = {
           success: false,
-          error: 'Authentication required',
-        });
+          error: 'Authentication required'
+        };
+        const jsonString = JSON.stringify(errorResponse);
+        return reply.status(401).type('application/json').send(jsonString);
       }
 
-      // Validate request body
-      const validatedData = CreateTeamSchema.parse(request.body);
+      // TypeScript type assertion (Fastify has already validated)
+      const { name, description } = request.body as CreateTeamRequest;
 
       // Check if user can create more teams (3 team limit)
       const canCreate = await TeamService.canUserCreateTeam(request.user.id);
       if (!canCreate) {
-        return reply.status(400).send({
+        const errorResponse: ErrorResponse = {
           success: false,
-          error: 'You have reached the maximum limit of 3 teams',
-        });
+          error: 'You have reached the maximum limit of 3 teams'
+        };
+        const jsonString = JSON.stringify(errorResponse);
+        return reply.status(400).type('application/json').send(jsonString);
       }
 
       // Create the team
       const team = await TeamService.createTeam({
-        name: validatedData.name,
-        description: validatedData.description,
+        name,
+        description,
         owner_id: request.user.id,
       });
 
-      return reply.status(201).send({
+      const successResponse: TeamSuccessResponse = {
         success: true,
         data: team,
-        message: 'Team created successfully',
-      });
+        message: 'Team created successfully'
+      };
+      const jsonString = JSON.stringify(successResponse);
+      return reply.status(201).type('application/json').send(jsonString);
     } catch (error) {
-      if (error instanceof ZodError) {
-        return reply.status(400).send({
-          success: false,
-          error: 'Validation error',
-          details: error.issues,
-        });
-      }
-
       if (error instanceof Error) {
         // Handle specific team creation errors
         if (error.message.includes('slug')) {
-          return reply.status(400).send({
+          const errorResponse: ErrorResponse = {
             success: false,
-            error: 'Team name conflicts with existing team',
-          });
+            error: 'Team name conflicts with existing team'
+          };
+          const jsonString = JSON.stringify(errorResponse);
+          return reply.status(400).type('application/json').send(jsonString);
         }
       }
 
-      fastify.log.error(error, 'Error creating team');
-      return reply.status(500).send({
+      server.log.error(error, 'Error creating team');
+      const errorResponse: ErrorResponse = {
         success: false,
-        error: 'Failed to create team',
-      });
+        error: 'Failed to create team'
+      };
+      const jsonString = JSON.stringify(errorResponse);
+      return reply.status(500).type('application/json').send(jsonString);
     }
   });
 }

services/backend/api-spec.yaml

@@ -1,98 +1,118 @@
-import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
-import { createSchema } from 'zod-openapi';
+import type { FastifyInstance, FastifyRequest } from 'fastify';
 import { TeamService } from '../../services/teamService';
 import { requirePermission } from '../../middleware/roleMiddleware';
-import { ErrorResponseSchema } from './schemas';
+import {
+  TEAM_ID_PARAMS_SCHEMA,
+  DELETE_SUCCESS_RESPONSE_SCHEMA,
+  ERROR_RESPONSE_SCHEMA,
+  type TeamIdParams,
+  type DeleteSuccessResponse,
+  type ErrorResponse
+} from './schemas';
 
-export default async function deleteTeamRoute(fastify: FastifyInstance) {
+export default async function deleteTeamRoute(server: FastifyInstance) {
   // DELETE /teams/:id - Delete team
-  fastify.delete<{ Params: { id: string } }>('/teams/:id', {
+  server.delete('/teams/:id', {
+    preValidation: requirePermission('teams.delete'),
     schema: {
       tags: ['Teams'],
       summary: 'Delete team',
       description: 'Deletes a team from the system. Only team owners can delete teams. Default teams cannot be deleted.',
       security: [{ cookieAuth: [] }],
-      params: {
-        type: 'object',
-        properties: {
-          id: { type: 'string' }
-        },
-        required: ['id']
-      },
+      
+      // Fastify validation schema
+      params: TEAM_ID_PARAMS_SCHEMA,
+      
       response: {
         200: {
-          type: 'object',
-          properties: {
-            success: { type: 'boolean' },
-            message: { type: 'string' }
-          },
-          required: ['success', 'message']
+          ...DELETE_SUCCESS_RESPONSE_SCHEMA,
+          description: 'Team deleted successfully'
+        },
+        400: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Bad Request - Cannot delete default team or team has active resources'
+        },
+        401: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Unauthorized - Authentication required'
+        },
+        403: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Forbidden - Insufficient permissions or not team owner'
         },
-        400: createSchema(ErrorResponseSchema.describe('Bad Request - Cannot delete default team or team has active resources')),
-        401: createSchema(ErrorResponseSchema.describe('Unauthorized - Authentication required')),
-        403: createSchema(ErrorResponseSchema.describe('Forbidden - Insufficient permissions')),
-        404: createSchema(ErrorResponseSchema.describe('Not Found - Team not found')),
-        500: createSchema(ErrorResponseSchema.describe('Internal Server Error'))
+        404: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Not Found - Team not found'
+        },
+        500: {
+          ...ERROR_RESPONSE_SCHEMA,
+          description: 'Internal Server Error'
+        }
       }
     },
-    preValidation: requirePermission('teams.delete'),
-  }, async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+  }, async (request: FastifyRequest<{ Params: TeamIdParams }>, reply) => {
     try {
-      if (!request.user) {
-        return reply.status(401).send({
-          success: false,
-          error: 'Authentication required',
-        });
-      }
-
-      const teamId = request.params.id;
+      // TypeScript types are now properly inferred from route definition
+      const { id: teamId } = request.params;
 
       // Check if team exists
       const existingTeam = await TeamService.getTeamById(teamId);
       if (!existingTeam) {
-        return reply.status(404).send({
+        const errorResponse: ErrorResponse = {
           success: false,
-          error: 'Team not found',
-        });
+          error: 'Team not found'
+        };
+        const jsonString = JSON.stringify(errorResponse);
+        return reply.status(404).type('application/json').send(jsonString);
       }
 
-      // Check if user is team owner
-      if (existingTeam.owner_id !== request.user.id) {
-        return reply.status(403).send({
+      // Check if user is team owner (user is guaranteed to exist due to preValidation)
+      if (existingTeam.owner_id !== request.user!.id) {
+        const errorResponse: ErrorResponse = {
           success: false,
-          error: 'Only team owners can delete teams',
-        });
+          error: 'Only team owners can delete teams'
+        };
+        const jsonString = JSON.stringify(errorResponse);
+        return reply.status(403).type('application/json').send(jsonString);
       }
 
       // Check if it's a default team
       if (existingTeam.is_default) {
-        return reply.status(400).send({
+        const errorResponse: ErrorResponse = {
           success: false,
-          error: 'Default teams cannot be deleted',
-        });
+          error: 'Default teams cannot be deleted'
+        };
+        const jsonString = JSON.stringify(errorResponse);
+        return reply.status(400).type('application/json').send(jsonString);
       }
 
       // Delete the team
       await TeamService.deleteTeam(teamId);
 
-      return reply.status(200).send({
+      const successResponse: DeleteSuccessResponse = {
         success: true,
-        message: 'Team deleted successfully',
-      });
+        message: 'Team deleted successfully'
+      };
+      const jsonString = JSON.stringify(successResponse);
+      return reply.status(200).type('application/json').send(jsonString);
     } catch (error) {
       if (error instanceof Error && error.message.includes('active resources')) {
-        return reply.status(400).send({
+        const errorResponse: ErrorResponse = {
           success: false,
-          error: 'Cannot delete team with active resources',
-        });
+          error: 'Cannot delete team with active resources'
+        };
+        const jsonString = JSON.stringify(errorResponse);
+        return reply.status(400).type('application/json').send(jsonString);
       }
 
-      fastify.log.error(error, 'Error deleting team');
-      return reply.status(500).send({
+      server.log.error(error, 'Error deleting team');
+      const errorResponse: ErrorResponse = {
         success: false,
         error: 'Failed to delete team',
-        details: error instanceof Error ? error.message : 'Unknown error'
-      });
+        details: [error instanceof Error ? error.message : 'Unknown error']
+      };
+      const jsonString = JSON.stringify(errorResponse);
+      return reply.status(500).type('application/json').send(jsonString);
     }
   });
 }