Merge branch 'alpha' into passenger/feat/iam-integration

apps/edr-passenger-api/src/modules/passengers/passengers.controller.ts

@@ -1,11 +1,12 @@
-import { Body, Controller, Get, Param, Post, UseGuards, Query } from '@nestjs/common';
+import { Body, Controller, Get, Param, Post, UseGuards, Query, Request } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiBearerAuth, ApiResponse, ApiQuery } from '@nestjs/swagger';
 import { PassengersService } from './passengers.service';
-import { CreateTravelerProfileDto, CreateSavedRouteDto, VerifyFaydaDto, RegisterInternationalPassengerDto } from './passengers.dto';
+import { CreateTravelerProfileDto, CreateSavedRouteDto, VerifyFaydaDto, SavePassengersDto, RegisterPassengerDto } from './passengers.dto';
 import { JwtGuard } from '../../common/jwt.guard';
 import { VerifaydaService } from '../verifayda/verifayda.service';
+import { OptionalJwtGuard } from '../verifayda/optional-jwt.guard';
 
-@ApiTags('Passenger')
+@ApiTags('Passengers')
 @Controller('passengers')
 export class PassengersController {
   constructor(
@@ -55,14 +56,51 @@ export class PassengersController {
   @Post('verify-fayda')
   @ApiOperation({
     summary: 'Verify Ethiopian national ID via Verifayda 2.0',
-    description: `Verifies Ethiopian national ID and retrieves passenger data from government database.
+    description: `**Standalone endpoint for pre-verification of Ethiopian national IDs**
 
+---
+
+### Purpose
+Pre-verify national ID to auto-fill passenger registration form before submission.
+
+---
+
+### Flow
+
+1. User enters national ID in form
+
+2. Frontend calls \`POST /passengers/verify-fayda\`
+
+3. API queries Verifayda 2.0 government database
+
+4. Returns verified passenger data (name, DOB, gender)
+
+5. Frontend auto-fills form with verified data
+
+6. User submits form via \`POST /passengers/register\`
+
+---
+
+### Features
 - Real-time verification via Verifayda 2.0 API
-- Retrieves verified passenger data (name, DOB, gender, nationality)
-- National IDs NOT stored (policy compliant)
+- Retrieves verified data: name, date of birth, gender, nationality
+- **National IDs NOT stored** (policy compliant)
 - Only for Ethiopian nationals with national ID
-- Non-Ethiopians should use passport (no verification required)
-- Returns passenger details for booking form auto-fill`,
+- Non-Ethiopians use passport (no verification)
+
+---
+
+### Important Notes
+- This is a **read-only** verification endpoint
+- Does NOT save passenger data to database
+- Use \`POST /passengers/register\` to actually register
+- Falls back to manual entry if Verifayda disabled or fails
+
+---
+
+### Authentication
+- **Public endpoint** (no authentication required)
+- Can be called before login/registration`,
   })
   @ApiResponse({ 
     status: 200, 
@@ -84,21 +122,143 @@ export class PassengersController {
     return this.verifaydaService.verifyNationalId(dto.nationalId);
   }
 
-  @Post('register-international')
+  @Post('register')
+  @UseGuards(OptionalJwtGuard)
+  @ApiBearerAuth('JWT-auth')
   @ApiOperation({
-    summary: 'Register international passenger with passport details',
-    description: `Saves international passenger profile for booking.
+    summary: 'Universal passenger registration endpoint',
+    description: `**Single endpoint for all passenger registration scenarios**
 
-- For non-Ethiopian passengers (Djiboutian, Kenyan, etc.)
-- Collects passport information
-- No government verification required
-- Profile saved for future bookings
-- Can be used by logged-in users or guest users (via deviceId)`,
+---
+
+### Automatic Detection
+The API automatically detects:
+- **Passenger Type**: Ethiopian (nationalId) vs International (passportNumber)
+- **Authentication**: Logged-in (JWT token) vs Guest (deviceId)
+- **Verification**: Auto-attempts Fayda for Ethiopian nationals
+
+---
+
+### Scenarios Handled
+
+#### 1. Guest Ethiopian Passenger
+- Provide: \`nationalId\`, \`deviceId\`
+- Behavior: Attempts Fayda verification → Saves to SavedPassengerProfile
+- Response: \`verified: true/false\`, \`linked: false\`
+
+#### 2. Guest International Passenger
+- Provide: \`passportNumber\`, \`passportCountry\`, \`deviceId\`
+- Behavior: No verification → Saves to SavedPassengerProfile
+- Response: \`verified: false\`, \`linked: false\`
+
+#### 3. Logged-in Ethiopian Passenger
+- Provide: JWT token + \`nationalId\`
+- Behavior: Attempts Fayda verification → Updates user profile
+- Response: \`verified: true/false\`, \`linked: true\`
+
+#### 4. Logged-in International Passenger
+- Provide: JWT token + \`passportNumber\`, \`passportCountry\`
+- Behavior: No verification → Updates user profile
+- Response: \`verified: false\`, \`linked: true\`
+
+---
+
+### Authentication
+- **Optional JWT Bearer Token** (OptionalJwtGuard)
+- Token present → Links to user account
+- No token → Saves as guest (requires deviceId)
+
+---
+
+### Benefits
+- Single endpoint for all scenarios
+- Auto-detects passenger type and flow
+- Graceful fallback if Fayda fails
+- Consistent response structure
+
+---
+
+### Replaces
+- Manual verification + save flows`,
   })
-  @ApiResponse({ status: 201, description: 'International passenger profile saved successfully' })
-  @ApiResponse({ status: 400, description: 'Invalid passport details' })
-  registerInternational(@Body() dto: RegisterInternationalPassengerDto) {
-    return this.service.registerInternational(dto);
+  @ApiResponse({ 
+    status: 201, 
+    description: 'Passenger registered successfully',
+    schema: {
+      example: {
+        id: 'uuid-123',
+        passengerName: 'Abebe Kebede',
+        dateOfBirth: '1985-03-15T00:00:00.000Z',
+        nationality: 'Ethiopian',
+        verified: true,
+        linked: false,
+        message: 'Passenger details saved for guest booking'
+      }
+    }
+  })
+  @ApiResponse({ 
+    status: 400, 
+    description: 'Validation error or verification failed',
+    schema: {
+      example: {
+        statusCode: 400,
+        message: 'Validation failed',
+        error: 'Bad Request'
+      }
+    }
+  })
+  @ApiResponse({ 
+    status: 401, 
+    description: 'Invalid JWT token (only if token provided but invalid)' 
+  })
+  registerPassenger(@Body() dto: RegisterPassengerDto, @Request() req: any) {
+    const userId = req.user?.userId;
+    return this.service.registerPassenger({ ...dto, userId });
+  }
+
+  @Post('save-details')
+  @ApiOperation({
+    summary: '[LEGACY] Save all passenger details before seat selection',
+    description: `**Note:** This endpoint is legacy. Consider using \`POST /passengers/register\` instead.
+
+Saves all passenger details to database before proceeding to seat selection.
+
+- Required step in booking flow
+- Saves details for all passengers in booking
+- Supports both logged-in users and guests
+- Prevents data loss if user navigates away
+
+**Migration:** Use \`POST /passengers/register\` for new implementations.`,
+  })
+  @ApiResponse({ 
+    status: 201, 
+    description: 'Passenger details saved successfully',
+    schema: {
+      example: {
+        count: 2,
+        passengerIds: ['uuid-1', 'uuid-2'],
+        passengers: [
+          {
+            id: 'uuid-1',
+            passengerName: 'John Doe',
+            dateOfBirth: '1990-01-01T00:00:00.000Z',
+            nationality: 'Ethiopian'
+          },
+          {
+            id: 'uuid-2',
+            passengerName: 'Jane Doe',
+            dateOfBirth: '1992-05-15T00:00:00.000Z',
+            nationality: 'Ethiopian'
+          }
+        ],
+        message: 'Passenger details saved successfully'
+      }
+    }
+  })
+  @ApiResponse({ status: 400, description: 'Validation error - passengers array required' })
+  savePassengers(@Body() body: any) {
+    const passengers = body.passengers || (Array.isArray(body) ? body : [body]);
+    return this.service.savePassengers(passengers, body.userId, body.deviceId);
   }
 
   @Post('traveler-profiles')