refactor(payment): centralize invoice processing with detailed tracking and configurable logging

apps/edr-freight-api/src/modules/bookings/booking-payment.controller.ts

@@ -1,180 +0,0 @@
-import {
-    Body,
-    Controller,
-    Get,
-    HttpStatus,
-    Post,
-    Query,
-    Res,
-} from "@nestjs/common";
-import {
-    ApiTags,
-    ApiOperation,
-    ApiQuery,
-    ApiOkResponse,
-    ApiProduces,
-} from "@nestjs/swagger";
-import { Response } from "express";
-import { Public } from "@edr/api-common";
-import { Freight } from "@edr/types";
-
-import { BillingService } from "../billing/billing.service";
-import {
-    InitiatePaymentDto,
-    InitiateResponseDto,
-    PaymentMethodTypeEnum,
-    PaymentPlatformDto,
-} from "../payment/payments.dto";
-
-/**
- * Booking-payment entrypoints. This is the ONE place that knows a payment is for a
- * booking — it maps the request to {@link Freight.InvoiceSource.Booking} and hands
- * off to billing, which resolves the invoice/amount and drives the gateway. Billing
- * and payment stay source-agnostic; the booking knowledge lives here, in the domain.
- * Routes are unchanged (`/payments/*`) so the portal is unaffected.
- */
-@ApiTags("Payment")
-@Controller("payments")
-export class BookingPaymentController {
-    constructor(private readonly billing: BillingService) { }
-
-    @Post("initiate")
-    @ApiOperation({
-        summary: "Initiate payment for a freight booking",
-        description: "Charges the booking's open invoice through the payment gateway.",
-    })
-    @ApiOkResponse({ type: InitiateResponseDto })
-    initiate(@Body() dto: InitiatePaymentDto): Promise<InitiateResponseDto> {
-        return this.billing.payInvoice(Freight.InvoiceSource.Booking, dto.bookingId, {
-            method: dto.method,
-            platform: dto.platform,
-            payerAccount: dto.payerAccount,
-            returnUrl: dto.returnUrl,
-            failureUrl: dto.failureUrl,
-        });
-    }
-
-    @Get("checkout")
-    @Public()
-    @ApiOperation({
-        summary: "Browser checkout redirect",
-        description:
-            "Charges the booking's invoice and returns an HTML page that auto-redirects to the provider checkout URL. Open directly in a browser tab.",
-    })
-    @ApiQuery({ name: "bookingId", required: true })
-    @ApiQuery({ name: "method", enum: PaymentMethodTypeEnum, required: true })
-    @ApiQuery({ name: "platform", enum: ["web", "mobile"], required: false })
-    @ApiProduces("text/html")
-    async checkout(
-        @Query("bookingId") bookingId: string,
-        @Query("method") method: PaymentMethodTypeEnum,
-        @Query("platform") platform: PaymentPlatformDto = "web",
-        @Res() res: Response,
-    ) {
-        if (!bookingId) {
-            return res
-                .status(HttpStatus.BAD_REQUEST)
-                .type("html")
-                .send(this.buildErrorHtml("Missing required query parameter: bookingId"));
-        }
-        if (!method || !Object.values(PaymentMethodTypeEnum).includes(method)) {
-            return res
-                .status(HttpStatus.BAD_REQUEST)
-                .type("html")
-                .send(this.buildErrorHtml("Missing or invalid query parameter: method"));
-        }
-
-        try {
-            const result = await this.billing.payInvoice(
-                Freight.InvoiceSource.Booking,
-                bookingId,
-                { method, platform },
-            );
-            const url =
-                result.clientAction?.type === "REDIRECT" ? result.clientAction.url : undefined;
-
-            if (url) {
-                return res.status(HttpStatus.OK).type("html").send(this.buildRedirectHtml(url));
-            }
-            return res
-                .status(HttpStatus.OK)
-                .type("html")
-                .send(this.buildStatusHtml(result.status, result.intentId));
-        } catch (err: unknown) {
-            const message = err instanceof Error ? err.message : "An unexpected error occurred";
-            return res.status(HttpStatus.OK).type("html").send(this.buildErrorHtml(message));
-        }
-    }
-
-    private buildRedirectHtml(url: string): string {
-        const escaped = url.replace(/\"/g, "&quot;");
-        return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta http-equiv="refresh" content="0;url=${escaped}">
-  <title>Redirecting to payment…</title>
-  <style>
-    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
-    .spinner { width: 40px; height: 40px; border: 4px solid #e0e0e0; border-top-color: #1a73e8; border-radius: 50%; animation: spin .8s linear infinite; margin: 0 auto 20px; }
-    @keyframes spin { to { transform: rotate(360deg); } }
-    p { color: #555; margin: 0 0 16px; }
-    a { color: #1a73e8; }
-  </style>
-</head>
-<body>
-  <div class="card">
-    <div class="spinner"></div>
-    <p>Redirecting to payment provider…</p>
-    <p><a href="${escaped}">Click here if you are not redirected</a></p>
-  </div>
-  <script>window.location.href = "${escaped}";</script>
-</body>
-</html>`;
-    }
-
-    private buildStatusHtml(status: string, intentId: string): string {
-        return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Payment status</title>
-  <style>
-    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
-    .status { font-size: 1.1rem; font-weight: 600; color: #333; margin-bottom: 8px; }
-    small { color: #888; }
-  </style>
-</head>
-<body>
-  <div class="card">
-    <div class="status">${status}</div>
-    <small>Intent: ${intentId}</small>
-  </div>
-</body>
-</html>`;
-    }
-
-    private buildErrorHtml(message: string): string {
-        return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Payment error</title>
-  <style>
-    body { font-family: sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f5f5f5; }
-    .card { background: #fff; border-radius: 8px; padding: 40px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,.1); max-width: 400px; }
-    .error { color: #d32f2f; font-weight: 600; margin-bottom: 8px; }
-    p { color: #555; }
-  </style>
-</head>
-<body>
-  <div class="card">
-    <div class="error">Payment could not be initiated</div>
-    <p>${message}</p>
-  </div>
-</body>
-</html>`;
-    }
-}

apps/edr-freight-api/src/modules/bookings/booking-payment.service.ts

@@ -1,43 +0,0 @@
-import { Injectable, NotFoundException } from '@nestjs/common';
-import { Freight } from '@edr/types';
-import { BookingsRepository } from './bookings.repository';
-import { Booking } from './entities/booking.entity';
-import { assertBookingStatus } from './booking-status.util';
-import { InAppPaymentReceiptDto } from './dto/pay-booking.dto';
-import { BillingService } from '../billing/billing.service';
-import { PaymentMethodTypeEnum } from '../payment/payments.dto';
-export interface InAppPaymentReceipt extends InAppPaymentReceiptDto { }
-
-@Injectable()
-export class BookingPaymentService {
-  constructor(
-    private readonly bookingsRepository: BookingsRepository,
-    private readonly billing: BillingService,
-  ) { }
-
-  /**
-   * Start payment for a booking. The booking never touches the payment gateway
-   * directly — it charges its invoice through billing, which resolves the amount
-   * and drives the provider. Returns the provider redirect URL (empty when none).
-   */
-  async pay(bookingId: string): Promise<{ redirectUrl: string }> {
-    const booking = await this.requireBooking(bookingId);
-    assertBookingStatus(booking, ['FULLY_EXECUTED', 'SELECTED_FOR_BATCH', 'AWAITING_PAYMENT', '']);
-
-    const resp = await this.billing.payInvoice(Freight.InvoiceSource.Booking, bookingId, {
-      method: PaymentMethodTypeEnum.TELEBIRR,
-      platform: 'web',
-    });
-
-    const action = resp.clientAction as { type?: string; url?: string } | undefined;
-    return {
-      redirectUrl: action?.type === 'REDIRECT' ? (action.url ?? '') : '',
-    };
-  }
-
-  private async requireBooking(id: string): Promise<Booking> {
-    const booking = await this.bookingsRepository.findById(id);
-    if (!booking) throw new NotFoundException(`Booking ${id} not found`);
-    return booking;
-  }
-}

apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts

@@ -447,6 +447,7 @@ export class BookingTransitionService {
       "CHANGES_REQUESTED",
       "PENDING_APPROVAL",
       "CONTRACT_READY",
+      "OPERATION_REQUEST_PENDING",
     ]);
 
     await this.bookingsRepository.createReviewNote(

apps/edr-freight-api/src/modules/bookings/bookings.module.ts

@@ -14,13 +14,10 @@ import { BillingModule } from "../billing/billing.module";
 import { FirstMileModule } from "../first-mile/first-mile.module";
 import { BookingContractService } from "./booking-contract.service";
 import { BookingInvoiceService } from "./booking-invoice.service";
-import { BookingPaymentController } from "./booking-payment.controller";
-import { BookingPaymentService } from "./booking-payment.service";
 import { BookingPricingService } from "./booking-pricing.service";
 import { BookingReferenceDataService } from "./booking-reference-data.service";
 import { BookingTransitionService } from "./booking-transition.service";
 import { BookingsController } from "./bookings.controller";
-import { PayController } from "./pay.controller";
 import { BookingsRepository } from "./bookings.repository";
 import { ConsolidationService } from "./consolidation.service";
 import { BookingsService } from "./bookings.service";
@@ -69,7 +66,7 @@ import { TrainSchedulingModule } from "../train-scheduling/train-scheduling.modu
         config.get<ExchangeOptions>("app.cbeExchange") ?? {},
     }),
   ],
-  controllers: [BookingsController, PayController, BookingPaymentController],
+  controllers: [BookingsController],
   providers: [
     BookingsService,
     BookingsRepository,
@@ -79,7 +76,6 @@ import { TrainSchedulingModule } from "../train-scheduling/train-scheduling.modu
     BookingTransitionService,
     BookingContractService,
     BookingInvoiceService,
-    BookingPaymentService,
     ContractTemplateResolver,
     ContractViewModelBuilder,
     ContractPricingScheduleBuilder,

apps/edr-freight-api/src/modules/bookings/pay.controller.ts

@@ -1,27 +0,0 @@
-import { Controller, Param, ParseUUIDPipe, Post } from '@nestjs/common';
-import { ApiBearerAuth, ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
-
-import { BookingPaymentService } from './booking-payment.service';
-// import { BookingTransitionService } from './booking-transition.service';
-// import { InAppPaymentReceiptDto } from './dto/pay-booking.dto';
-// import { Booking } from './entities/booking.entity';
-// import { BookingNextStep } from './booking-next-step.util';
-
-@ApiTags('payments')
-@ApiBearerAuth()
-@Controller('bookings')
-export class PayController {
-  constructor(
-    private readonly paymentService: BookingPaymentService,
-    // private readonly transitionService: BookingTransitionService,
-  ) { }
-
-  @Post(':id/payment/pay')
-  @ApiOperation({ summary: 'Complete in-app payment (mock)' })
-  @ApiOkResponse({ description: 'Enriched booking with ephemeral payment receipt' })
-  async pay(@Param('id', ParseUUIDPipe) id: string) {
-    return await this.paymentService.pay(id);
-    // const abstract = await this.transitionService.enrichBookingResponse(booking);
-    // return { ...abstract, paymentReceipt: receipt };
-  }
-}