Merge pull request Nexacore-Org#360 from BigBen-7/feat/swagger-idempotency-feature-flags-e2e

feat: Swagger docs, idempotency guards, feature flag evaluation engine, and E2E test suite

Author: portableDD

.github/workflows/e2e-tests.yml

@@ -0,0 +1,106 @@
+name: E2E Integration Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+      - develop
+  push:
+    branches:
+      - main
+
+jobs:
+  e2e:
+    name: Run E2E Test Suite
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15-alpine
+        env:
+          POSTGRES_USER: nexafx
+          POSTGRES_PASSWORD: nexafx_test
+          POSTGRES_DB: nexafx_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      NODE_ENV: test
+      DB_HOST: localhost
+      DB_PORT: 5432
+      DB_USER: nexafx
+      DB_PASSWORD: nexafx_test
+      DB_NAME: nexafx_test
+      REDIS_HOST: localhost
+      REDIS_PORT: 6379
+      JWT_SECRET: e2e-test-jwt-secret-do-not-use-in-prod
+      REFRESH_TOKEN_SECRET: e2e-test-refresh-secret
+      OTP_SECRET: e2e-test-otp-secret
+      DISABLE_BULL: "true"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build application
+        run: npm run build
+
+      - name: Wait for PostgreSQL
+        run: |
+          until pg_isready -h localhost -p 5432 -U nexafx; do
+            echo "Waiting for postgres..."
+            sleep 2
+          done
+
+      - name: Run E2E tests
+        run: npm run test:e2e -- --testPathPattern="test/e2e"
+        timeout-minutes: 10
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-test-results
+          path: |
+            coverage/
+            test-results/
+          retention-days: 7
+
+      - name: Comment PR with test results
+        if: github.event_name == 'pull_request' && always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const outcome = '${{ job.status }}';
+            const emoji = outcome === 'success' ? '✅' : '❌';
+            const body = `${emoji} **E2E Tests**: ${outcome}\n\nSee [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details.`;
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body,
+            });

src/app.module.ts

@@ -28,13 +28,13 @@ import { TransactionRiskModule } from './modules/transaction-risk/transaction-ri
 import { WebhooksModule } from './modules/webhooks/webhooks.module';
 import { SecretsModule } from './modules/secrets/secrets.module';
 import { DataArchiveModule } from './modules/data-archive/data-archive.module';
+import { IdempotencyModule } from './idempotency/idempotency.module';
 import { GoalsModule } from './goals/goal.module';
 import { AnnouncementsModule } from './announcement/announcement.module';
 import { ComplianceModule } from './compliance-evidence/compliance.module';
 import { LedgerModule } from './double-entry-ledger/ledger.module';
 import { VersioningModule } from './versioning/versioning.module';
 import { InsightsModule } from './exxagerated/exxagerated.module';
-import { NotificationsModule as WebSocketNotificationsModule } from './web-sockets/notifications.module';
 
 const enableBull =
   process.env.NODE_ENV !== 'test' && process.env.DISABLE_BULL !== 'true';
@@ -96,6 +96,7 @@ const enableBull =
     WebhooksModule,
     SecretsModule,
     DataArchiveModule,
+    IdempotencyModule,
     GoalsModule,
     AnnouncementsModule,
     ComplianceModule,

src/double-entry-ledger/ledger.controller.ts

@@ -9,14 +9,19 @@ import {
   HttpCode,
   HttpStatus,
   ParseUUIDPipe,
+  UseInterceptors,
 } from '@nestjs/common';
 import {
   ApiTags,
   ApiBearerAuth,
   ApiOperation,
   ApiOkResponse,
   ApiCreatedResponse,
+  ApiHeader,
 } from '@nestjs/swagger';
+import { Idempotent } from '../idempotency/idempotency.decorator';
+import { IdempotencyGuard } from '../idempotency/idempotency.guard';
+import { IdempotencyInterceptor } from '../idempotency/idempotency.interceptor';
 import { LedgerService } from './ledger.service';
 import {
   CreateDoubleEntryDto,
@@ -36,8 +41,12 @@ export class LedgerController {
 
   @Post('entries')
   @HttpCode(HttpStatus.CREATED)
+  @Idempotent()
+  @UseGuards(IdempotencyGuard)
+  @UseInterceptors(IdempotencyInterceptor)
   @ApiCreatedResponse({ description: 'Double-entry posted successfully' })
   @ApiOperation({ summary: 'Post a balanced double-entry transaction' })
+  @ApiHeader({ name: 'Idempotency-Key', description: 'Unique key to prevent duplicate ledger entries (min 16 chars)', required: true })
   async postDoubleEntry(@Body() dto: CreateDoubleEntryDto) {
     return this.ledgerService.postDoubleEntry(dto);
   }

src/fx/fx-conversion.controller.ts

@@ -8,8 +8,13 @@ import {
   Query,
   Request,
   UseGuards,
+  UseInterceptors,
 } from '@nestjs/common';
+import { ApiTags, ApiBearerAuth, ApiOperation, ApiOkResponse, ApiCreatedResponse, ApiHeader } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../../../auth/guards/jwt-auth.guard';
+import { Idempotent } from '../../idempotency/idempotency.decorator';
+import { IdempotencyGuard } from '../../idempotency/idempotency.guard';
+import { IdempotencyInterceptor } from '../../idempotency/idempotency.interceptor';
 import { FxConversionService } from '../services/fx-conversion.service';
 import {
   ConversionHistoryDto,
@@ -19,6 +24,8 @@ import {
 } from '../dto/fx-conversion.dto';
 import { LoyaltyTier } from '../../loyalty/entities/loyalty-account.entity';
 
+@ApiTags('FX Conversion')
+@ApiBearerAuth('access-token')
 @UseGuards(JwtAuthGuard)
 @Controller('fx')
 export class FxConversionController {
@@ -35,6 +42,8 @@ export class FxConversionController {
    *  - regulatoryDisclosure text for the user's jurisdiction
    */
   @Get('convert/quote')
+  @ApiOperation({ summary: 'Get a locked FX conversion quote' })
+  @ApiOkResponse({ description: 'Quote with locked rate, fees, and TTL' })
   async getQuote(@Request() req, @Query() dto: GetQuoteDto) {
     const user = req.user;
     return this.fxService.createQuote(
@@ -57,6 +66,12 @@ export class FxConversionController {
    */
   @Post('convert')
   @HttpCode(HttpStatus.CREATED)
+  @Idempotent()
+  @UseGuards(IdempotencyGuard)
+  @UseInterceptors(IdempotencyInterceptor)
+  @ApiOperation({ summary: 'Execute a currency conversion at a locked quote rate' })
+  @ApiCreatedResponse({ description: 'Conversion executed successfully' })
+  @ApiHeader({ name: 'Idempotency-Key', description: 'Unique key to prevent duplicate conversions (min 16 chars)', required: true })
   async executeConversion(@Request() req, @Body() dto: ExecuteConversionDto) {
     return this.fxService.executeConversion(req.user.id, dto);
   }
@@ -72,6 +87,8 @@ export class FxConversionController {
    * Does NOT lock a quote — purely informational.
    */
   @Get('fees')
+  @ApiOperation({ summary: 'Get FX fee breakdown (informational, no quote lock)' })
+  @ApiOkResponse({ description: 'Fee breakdown with mid-rate, markup and total cost' })
   async getFees(@Request() req, @Query() dto: GetFeesDto) {
     return this.fxService.getFeeBreakdown(
       dto.fromCurrency.toUpperCase(),
@@ -87,6 +104,8 @@ export class FxConversionController {
    * Paginated conversion history — newest first.
    */
   @Get('convert/history')
+  @ApiOperation({ summary: 'Get paginated FX conversion history' })
+  @ApiOkResponse({ description: 'Paginated conversion history' })
   async getHistory(@Request() req, @Query() dto: ConversionHistoryDto) {
     return this.fxService.getHistory(req.user.id, dto);
   }

src/idempotency/cleanup.job.ts

@@ -0,0 +1,17 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+import { IdempotencyService } from './idempotency.service';
+
+@Injectable()
+export class IdempotencyCleanupJob {
+  private readonly logger = new Logger(IdempotencyCleanupJob.name);
+
+  constructor(private readonly idempotencyService: IdempotencyService) {}
+
+  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
+  async cleanupExpiredKeys(): Promise<void> {
+    this.logger.log('Running idempotency key cleanup...');
+    const deleted = await this.idempotencyService.cleanup();
+    this.logger.log(`Cleaned up ${deleted} expired idempotency keys`);
+  }
+}

src/idempotency/idempotency.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const IDEMPOTENCY_KEY = 'idempotency';
+export const Idempotent = () => SetMetadata(IDEMPOTENCY_KEY, true);

src/idempotency/idempotency.entity.ts

@@ -0,0 +1,24 @@
+import { Entity, Column, PrimaryColumn, CreateDateColumn, Index } from 'typeorm';
+
+@Entity('idempotency_keys')
+@Index(['createdAt'])
+@Index(['expiresAt'])
+export class IdempotencyKey {
+  @PrimaryColumn()
+  key: string;
+
+  @Column('text')
+  requestHash: string;
+
+  @Column('jsonb')
+  response: any;
+
+  @Column('int')
+  statusCode: number;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @Column({ type: 'timestamp', nullable: true })
+  expiresAt: Date;
+}

src/idempotency/idempotency.guard.ts

@@ -0,0 +1,72 @@
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  ConflictException,
+  BadRequestException,
+  UnprocessableEntityException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { IdempotencyService } from './idempotency.service';
+import { IDEMPOTENCY_KEY } from './idempotency.decorator';
+
+const MIN_KEY_LENGTH = 16;
+
+@Injectable()
+export class IdempotencyGuard implements CanActivate {
+  constructor(
+    private reflector: Reflector,
+    private idempotencyService: IdempotencyService,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const isIdempotent = this.reflector.get<boolean>(
+      IDEMPOTENCY_KEY,
+      context.getHandler(),
+    );
+
+    if (!isIdempotent) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest();
+    const idempotencyKey = request.headers['idempotency-key'];
+
+    if (!idempotencyKey) {
+      throw new BadRequestException('Idempotency-Key header is required');
+    }
+
+    if (idempotencyKey.length < MIN_KEY_LENGTH) {
+      throw new BadRequestException(
+        `Idempotency-Key must be at least ${MIN_KEY_LENGTH} characters`,
+      );
+    }
+
+    const requestHash = this.idempotencyService.hashRequest(
+      request.method,
+      request.url,
+      request.body,
+    );
+
+    const existing = await this.idempotencyService.findByKey(idempotencyKey);
+
+    if (existing) {
+      if (existing.requestHash !== requestHash) {
+        throw new UnprocessableEntityException(
+          'Idempotency-Key already used with different request parameters',
+        );
+      }
+
+      // Return cached response
+      request.idempotencyResponse = {
+        statusCode: existing.statusCode,
+        body: existing.response,
+      };
+    }
+
+    request.idempotencyKey = idempotencyKey;
+    request.requestHash = requestHash;
+
+    return true;
+  }
+}

src/idempotency/idempotency.interceptor.ts

@@ -0,0 +1,39 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable, of } from 'rxjs';
+import { tap } from 'rxjs/operators';
+import { IdempotencyService } from './idempotency.service';
+
+@Injectable()
+export class IdempotencyInterceptor implements NestInterceptor {
+  constructor(private idempotencyService: IdempotencyService) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest();
+    const response = context.switchToHttp().getResponse();
+
+    // Return cached response immediately if it exists
+    if (request.idempotencyResponse) {
+      response.status(request.idempotencyResponse.statusCode);
+      return of(request.idempotencyResponse.body);
+    }
+
+    return next.handle().pipe(
+      tap(async (data) => {
+        // Cache response after successful commit (post-response)
+        if (request.idempotencyKey) {
+          await this.idempotencyService.store(
+            request.idempotencyKey,
+            request.requestHash,
+            data,
+            response.statusCode,
+          );
+        }
+      }),
+    );
+  }
+}