Ticket

Empty container returns now generate a downloadable Equipment Interchange Receipt: container number & size, exact return timestamp, depot/location, condition, and the carrier/booking reference. Customers can download it from their booking's Documents tab (own-booking returns only); staff can pull any via the same endpoint.
2026-09-08 15:58:18 +00:00 · 2026-08-21 08:15:31 +00:00
parent fbb169469f
commit 8181834037
94 changed files with 477 additions and 19 deletions
--- a/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts
@@ -1,8 +1,13 @@
-import { Body, Controller, Get, Param, ParseUUIDPipe, Post, Query } from '@nestjs/common';
+import { Body, Controller, Get, NotFoundException, Param, ParseUUIDPipe, Post, Query, Res } from '@nestjs/common';
 import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import type { Response } from 'express';
+import { CurrentUser } from '@edr/api-common';
+import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';

-import { BookingStaff } from '../../common/booking-guards';
+import { BookingStaff, MixedAudience } from '../../common/booking-guards';
+import { hasFreightPermission } from '../../common/freight-permission.util';
 import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
+import { BookingsService } from '../bookings/bookings.service';
 import {
  AssignCustomsRiskDto,
  CreateDjiboutiIncidentDto,
@@ -19,30 +24,38 @@ import { ImportOperationsService } from './import-operations.service';
@ApiBearerAuth()
@Controller('import-operations')
 // Post-booking customs / import-operations actions are GL/Ops work, mirroring the
-// contracts controller's GL operational endpoints (risk, duty, milestones).
-@BookingStaff(FREIGHT_PERMS.bookings.operations)
+// contracts controller's GL operational endpoints (risk, duty, milestones). No
+// class-level guard: the equipment interchange receipt below is customer-reachable,
+// every other route here stays staff-only via its own @BookingStaff.
 export class ImportOperationsController {
-  constructor(private readonly service: ImportOperationsService) {}
+  constructor(
+    private readonly service: ImportOperationsService,
+    private readonly bookingsService: BookingsService,
+  ) {}

  @Get('djibouti-incidents')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 8: list Djibouti import incidents' })
  listIncidents(@Query('bookingId') bookingId?: string) {
    return this.service.listIncidents(bookingId);
  }

  @Post('djibouti-incidents')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 8: report a Djibouti import incident / exception' })
  createIncident(@Body() dto: CreateDjiboutiIncidentDto) {
    return this.service.createIncident(dto);
  }

  @Get('customs/:bookingId')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 12: import customs finalization state' })
  getCustoms(@Param('bookingId', ParseUUIDPipe) bookingId: string) {
    return this.service.getCustoms(bookingId);
  }

  @Post('customs/:bookingId/documents')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 12: upload IM4/IM5/T1/permit/payment-slip documents' })
  uploadCustomsDocument(
    @Param('bookingId', ParseUUIDPipe) bookingId: string,
@@ -52,6 +65,7 @@ export class ImportOperationsController {
  }

  @Post('customs/:bookingId/declaration')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 12: record declaration serial number' })
  recordDeclaration(
    @Param('bookingId', ParseUUIDPipe) bookingId: string,
@@ -61,6 +75,7 @@ export class ImportOperationsController {
  }

  @Post('customs/:bookingId/notify-duties-taxes')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 12: notify duties and taxes' })
  notifyDutiesTaxes(
    @Param('bookingId', ParseUUIDPipe) bookingId: string,
@@ -70,6 +85,7 @@ export class ImportOperationsController {
  }

  @Post('customs/:bookingId/duties-taxes-paid')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 12: mark duties and taxes paid' })
  markDutiesTaxesPaid(
    @Param('bookingId', ParseUUIDPipe) bookingId: string,
@@ -79,12 +95,14 @@ export class ImportOperationsController {
  }

  @Post('customs/:bookingId/risk')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 12: assign customs risk' })
  assignRisk(@Param('bookingId', ParseUUIDPipe) bookingId: string, @Body() dto: AssignCustomsRiskDto) {
    return this.service.assignRisk(bookingId, dto);
  }

  @Post('customs/:bookingId/release-permitted')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 12: mark import release permitted' })
  markReleasePermitted(
    @Param('bookingId', ParseUUIDPipe) bookingId: string,
@@ -94,18 +112,21 @@ export class ImportOperationsController {
  }

  @Get('empty-container-returns')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 16: list empty container returns' })
  listEmptyReturns() {
    return this.service.listEmptyReturns();
  }

  @Post('empty-container-returns')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 16: create an empty container return record' })
  createEmptyReturn(@Body() dto: CreateEmptyContainerReturnDto) {
    return this.service.createEmptyReturn(dto);
  }

  @Post('empty-container-returns/load-on-train')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({
    summary: 'Load returned empties onto an export train (1×40ft or 2×20ft per wagon)',
  })
@@ -114,6 +135,7 @@ export class ImportOperationsController {
  }

  @Post('empty-container-returns/:id/status')
+  @BookingStaff(FREIGHT_PERMS.bookings.operations)
  @ApiOperation({ summary: 'Batch 16: advance empty container return workflow' })
  updateEmptyReturnStatus(
    @Param('id', ParseUUIDPipe) id: string,
@@ -121,4 +143,53 @@ export class ImportOperationsController {
  ) {
    return this.service.updateEmptyReturnStatus(id, dto);
  }
+
+  @Get('bookings/:bookingId/empty-container-returns')
+  @MixedAudience(FREIGHT_PERMS.bookings.operations)
+  @ApiOperation({ summary: 'List empty container returns for a booking (customer portal)' })
+  async listEmptyReturnsForBooking(
+    @Param('bookingId', ParseUUIDPipe) bookingId: string,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    await this.assertCanAccessBooking(user, bookingId);
+    return this.service.listEmptyReturnsForBooking(bookingId);
+  }
+
+  @Get('empty-container-returns/:id/document')
+  @MixedAudience(FREIGHT_PERMS.bookings.operations)
+  @ApiOperation({ summary: 'Download the equipment interchange receipt PDF (customer portal)' })
+  async equipmentInterchangeDocument(
+    @Param('id', ParseUUIDPipe) id: string,
+    @CurrentUser() user: TCurrentUser,
+    @Res() res: Response,
+  ) {
+    const row = await this.service.getEmptyReturnOrThrow(id);
+    // A standalone (no-booking) return has no owner to check against, so it
+    // stays staff-only.
+    if (!row.bookingId) {
+      await this.assertCanAccessBooking(user, null);
+    } else {
+      await this.assertCanAccessBooking(user, row.bookingId);
+    }
+
+    const { filename, buffer } = await this.service.equipmentInterchangeDocument(row);
+    res.setHeader('Content-Type', 'application/pdf');
+    res.setHeader('Content-Disposition', `inline; filename="${filename}"`);
+    res.setHeader('Content-Length', buffer.length);
+    return res.send(buffer);
+  }
+
+  /**
+   * Staff pass on permission alone. A customer must own the booking; `null`
+   * (a standalone, booking-less return) has no owner for a customer to match,
+   * so it 404s them the same way a foreign booking would.
+   */
+  private async assertCanAccessBooking(user: TCurrentUser, bookingId: string | null): Promise<void> {
+    if (hasFreightPermission(user, FREIGHT_PERMS.bookings.operations)) return;
+    if (!bookingId) {
+      throw new NotFoundException('Not found');
+    }
+    const booking = await this.bookingsService.findById(bookingId);
+    await this.bookingsService.assertCustomerCanAccessBooking(user?.id, booking);
+  }
 }
--- a/apps/edr-freight-api/src/modules/import-operations/import-operations.module.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/import-operations.module.ts
@@ -1,6 +1,8 @@
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';

+import { BookingsModule } from '../bookings/bookings.module';
+import { WarehousesModule } from '../warehouses/warehouses.module';
 import { DjiboutiIncident } from './entities/djibouti-incident.entity';
 import { EmptyContainerReturn } from './entities/empty-container-return.entity';
 import { ImportCustomsFinalization } from './entities/import-customs-finalization.entity';
@@ -14,6 +16,11 @@ import { ImportOperationsService } from './import-operations.service';
      ImportCustomsFinalization,
      EmptyContainerReturn,
    ]),
+    // WarehouseReleaseDocumentService (the shared PDF renderer) for the
+    // equipment interchange receipt; BookingsModule for the customer
+    // ownership check on that same route.
+    WarehousesModule,
+    BookingsModule,
  ],
  controllers: [ImportOperationsController],
  providers: [ImportOperationsService],
--- a/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts
@@ -2,6 +2,9 @@ import { BadRequestException, Injectable, NotFoundException } from '@nestjs/comm
 import { InjectRepository } from '@nestjs/typeorm';
 import { In, Repository } from 'typeorm';

+import { LogoSettingsService } from '../logo-settings/logo-settings.service';
+import { logoImageCss, logoMarkup } from '../billing/documents/logo-markup.util';
+import { WarehouseReleaseDocumentService } from '../warehouses/warehouse-release-document.service';
 import {
  CreateDjiboutiIncidentDto,
  CreateEmptyContainerReturnDto,
@@ -39,6 +42,8 @@ export class ImportOperationsService {
    private readonly customs: Repository<ImportCustomsFinalization>,
    @InjectRepository(EmptyContainerReturn)
    private readonly emptyReturns: Repository<EmptyContainerReturn>,
+    private readonly pdfDocuments: WarehouseReleaseDocumentService,
+    private readonly logoSettings: LogoSettingsService,
  ) {}

  listIncidents(bookingId?: string) {
@@ -150,6 +155,10 @@ export class ImportOperationsService {
    return this.emptyReturns.find({ order: { createdAt: 'DESC' } as never });
  }

+  listEmptyReturnsForBooking(bookingId: string) {
+    return this.emptyReturns.find({ where: { bookingId }, order: { createdAt: 'DESC' } as never });
+  }
+
  async createEmptyReturn(dto: CreateEmptyContainerReturnDto) {
    const returnDate = dto.returnDate ? new Date(dto.returnDate) : new Date();
    return this.emptyReturns.save(
@@ -248,6 +257,142 @@ export class ImportOperationsService {
    return this.emptyReturns.findOneOrFail({ where: { id } });
  }

+  async getEmptyReturnOrThrow(id: string): Promise<EmptyContainerReturn> {
+    const row = await this.emptyReturns.findOne({ where: { id } });
+    if (!row) {
+      throw new NotFoundException(`Empty container return ${id} not found`);
+    }
+    return row;
+  }
+
+  /**
+   * Equipment Interchange Receipt — container number/size, exact return
+   * timestamp, depot, condition, and the carrier/booking reference that ties
+   * the box back to its bill of lading. Handed to the customer to download.
+   */
+  async equipmentInterchangeDocument(
+    row: EmptyContainerReturn,
+  ): Promise<{ filename: string; buffer: Buffer }> {
+    const booking = row.bookingId
+      ? ((
+          await this.emptyReturns.manager.query(
+            `SELECT b.reference, c.name AS company_name
+               FROM freight.bookings b
+               LEFT JOIN freight.companies c ON c.id = b.company_id
+              WHERE b.id = $1`,
+            [row.bookingId],
+          )
+        )[0] as { reference: string; company_name: string | null } | undefined)
+      : undefined;
+
+    const html = this.buildEquipmentInterchangeHtml(row, booking, {
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
+    });
+    const buffer = await this.pdfDocuments.renderDocumentHtml(html, 'Equipment interchange receipt');
+    return {
+      filename: `equipment-interchange-${row.containerNumber || row.id.slice(0, 8)}.pdf`,
+      buffer,
+    };
+  }
+
+  private buildEquipmentInterchangeHtml(
+    row: EmptyContainerReturn,
+    booking: { reference: string; company_name: string | null } | undefined,
+    opts: { logoImageUrl?: string | null },
+  ): string {
+    const esc = (value: unknown) =>
+      String(value ?? '-')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+    const dateTime = (value: unknown) =>
+      value ? new Date(value as string | Date).toLocaleString('en-GB', { dateStyle: 'medium', timeStyle: 'short' }) : '-';
+    const carrier =
+      row.returnedBy === 'EDR'
+        ? 'EDR Last Mile'
+        : row.returnedBy === 'CUSTOMER'
+          ? 'Customer Self-Haul'
+          : '-';
+
+    const rows: Array<[string, string]> = [
+      ['Container Number', row.containerNumber],
+      ['Container Size', row.containerSize ? `${row.containerSize}ft` : 'Not recorded'],
+      ['Date & Time of Return', dateTime(row.returnDate)],
+      ['Depot / Location', [row.facility, row.yard, row.zone].filter(Boolean).join(' — ') || '-'],
+      ['Condition Status', row.condition || 'Good — no exceptions noted'],
+      ['Carrier', carrier],
+      ['Booking / BOL Reference', booking?.reference || 'Standalone — no booking'],
+      ['Shipping Line / Customer', booking?.company_name || '-'],
+      ['Current Status', row.status.replace(/_/g, ' ')],
+      ['Handover Note', row.handoverNote || '-'],
+    ];
+
+    const rowsHtml = rows
+      .map(
+        ([label, value]) =>
+          `<tr><th>${esc(label)}</th><td>${esc(value)}</td></tr>`,
+      )
+      .join('');
+
+    return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>Equipment Interchange Receipt</title>
+  <style>
+    @page { size: A4; margin: 14mm; }
+    * { box-sizing: border-box; }
+    body { margin: 0; color: #0f172a; font-family: Arial, sans-serif; }
+    .top { display: flex; justify-content: space-between; align-items: flex-start; border-bottom: 3px solid #0f766e; padding-bottom: 12px; gap: 24px; }
+    .brand { font-size: 11px; color: #475569; text-transform: uppercase; letter-spacing: .08em; font-weight: 700; }
+    h1 { margin: 6px 0 0; font-size: 22px; line-height: 1.1; }
+    .meta { text-align: right; font-size: 11px; color: #475569; }
+    .meta strong { display: block; margin-top: 4px; color: #0f172a; font-size: 15px; }
+    ${logoImageCss()}
+    table { width: 100%; border-collapse: collapse; margin-top: 20px; }
+    th, td { border: 1px solid #cbd5e1; padding: 8px 10px; font-size: 11.5px; text-align: left; vertical-align: top; }
+    th { width: 220px; background: #f8fafc; color: #475569; font-weight: 700; }
+    .notice { margin-top: 16px; border-left: 4px solid #0f766e; background: #f0fdfa; padding: 10px 12px; font-size: 10.5px; color: #134e4a; }
+    .signatures { display: grid; grid-template-columns: repeat(2, 1fr); gap: 24px; margin-top: 40px; }
+    .line { border-top: 1px solid #334155; padding-top: 8px; font-size: 10px; color: #475569; min-height: 40px; }
+  </style>
+</head>
+<body>
+  <div class="top">
+    <div>
+      ${logoMarkup(opts.logoImageUrl)}
+      <div class="brand">Ethio-Djibouti Railway S.C.</div>
+      <h1>Equipment Interchange Receipt</h1>
+    </div>
+    <div class="meta">
+      Receipt No.
+      <strong>${esc(`EIR-${row.id.slice(0, 8).toUpperCase()}`)}</strong>
+      Generated: ${esc(new Date().toLocaleString('en-GB'))}
+    </div>
+  </div>
+
+  <table>
+    <tbody>
+      ${rowsHtml}
+    </tbody>
+  </table>
+
+  <div class="notice">
+    This receipt confirms the physical interchange of the equipment described above at the
+    depot/location and time stated. Both parties should verify the container number, size,
+    and condition recorded here before signing.
+  </div>
+
+  <div class="signatures">
+    <div class="line">Depot officer name / signature / date</div>
+    <div class="line">Customer or driver name / signature / date</div>
+  </div>
+</body>
+</html>`;
+  }
+
  private async getOrCreateCustoms(bookingId: string) {
    const existing = await this.customs.findOne({ where: { bookingId } });
    if (existing) return existing;