feat(bookings): surface cargo declared on the shipment request

A GENERAL + customs contract does not let the customer book directly: they
submit a shipment request, and initiateForShipmentRequest opens a BARE booking
from it — "the request itself carries the quantities; the instance carries
none". Between initiation and completeUnderContract the booking legitimately
holds no cargo, so the export reported 0 containers for a customer who had
declared, say, 2 x 20FT. 23 bookings on dev data are in that state.

Adds two columns and one filter reading booking_requests.requested_lines:
- "Requested cargo" — the declared lines as text ("2 x 20FT"), handling the
  bulk shape too (tons / item count), not only containers.
- "Requested containers" — the declared box count, with a matching min/max
  filter on the list and the export.

Deliberately a separate column rather than a fallback inside the real container
count: a declared 2 x 20FT is a request, not two boxes on a booking, and
merging them would overstate operational totals. The two compose instead —
Containers = 0 AND Requested containers >= 1 is exactly the set awaiting
completion after clearance.

requested_lines is free-form jsonb, so the container array is guarded by
jsonb_typeof before jsonb_array_elements; one malformed row would otherwise
500 the whole list.

apps/edr-freight-api/src/modules/bookings/booking-content.sql.spec.ts

@@ -5,6 +5,8 @@ import {
   bookingContentMatchSql,
   bookingContentSql,
   bookingHasContainerTypeSql,
+  bookingRequestedCargoSql,
+  bookingRequestedContainerCountSql,
 } from './booking-content.sql';
 
 describe('bookingContentSql', () => {
@@ -106,3 +108,39 @@ describe('bookingContainerVgmSql', () => {
     expect(sql).toContain('bc.deleted_at IS NULL');
   });
 });
+
+describe('requested (shipment-request) cargo', () => {
+  const cargo = bookingRequestedCargoSql('b');
+  const count = bookingRequestedContainerCountSql('b');
+
+  it('reads the request, never the booking or its container lines', () => {
+    for (const sql of [cargo, count]) {
+      expect(sql).toContain('freight.booking_requests br');
+      expect(sql).toContain('br.created_booking_id = b.id');
+      expect(sql).not.toContain('freight.booking_container');
+    }
+  });
+
+  // requested_lines is a free-form jsonb column; jsonb_array_elements throws on
+  // a non-array, which would 500 the whole list for one malformed row.
+  it('survives a requested_lines with no container array', () => {
+    for (const sql of [cargo, count]) {
+      expect(sql).toContain("jsonb_typeof(br.requested_lines->'containers') = 'array'");
+      expect(sql).toContain("ELSE '[]'::jsonb");
+    }
+  });
+
+  it('renders the bulk shape too, not only containers', () => {
+    expect(cargo).toContain("'bulk'->>'cargoWeightTons'");
+    expect(cargo).toContain("'bulk'->>'itemCount'");
+  });
+
+  it('counts 0 rather than NULL when no request exists', () => {
+    expect(count).toContain("COALESCE(SUM((l->>'quantity')::int), 0)");
+  });
+
+  it('ignores soft-deleted requests', () => {
+    expect(cargo).toContain('br.deleted_at IS NULL');
+    expect(count).toContain('br.deleted_at IS NULL');
+  });
+});

apps/edr-freight-api/src/modules/bookings/booking-content.sql.ts

@@ -98,3 +98,51 @@ export function bookingContainerVgmSql(alias = 'b'): string {
             WHERE bc.booking_id = ${alias}.id
               AND bc.deleted_at IS NULL)`;
 }
+
+/**
+ * Cargo the customer declared on the SHIPMENT REQUEST behind a booking, which
+ * is not the same fact as cargo on the booking itself.
+ *
+ * On a GENERAL + customs contract the customer cannot book directly: they
+ * submit a request (day + quantities), and `initiateForShipmentRequest` opens a
+ * BARE instance from it — "the request itself carries the quantities; the
+ * instance carries none". So between initiation and `completeUnderContract` the
+ * booking legitimately holds no cargo while the customer's declared quantities
+ * sit on `booking_requests.requested_lines`.
+ *
+ * Kept in its own column rather than folded into the real container count: a
+ * declared 2 × 20FT is a request, not two boxes on a booking, and merging the
+ * two would overstate operational totals.
+ */
+const REQUESTED_CONTAINER_LINES = `jsonb_array_elements(
+  CASE WHEN jsonb_typeof(br.requested_lines->'containers') = 'array'
+       THEN br.requested_lines->'containers'
+       ELSE '[]'::jsonb END)`;
+
+/** Human-readable declared cargo: "2 × 20FT", "12 t", "40 items". */
+export function bookingRequestedCargoSql(alias = 'b'): string {
+  return `(SELECT COALESCE(
+              (SELECT string_agg((l->>'quantity') || ' × ' || upper(l->>'containerSize'), ', '
+                                 ORDER BY l->>'containerSize')
+                 FROM ${REQUESTED_CONTAINER_LINES} AS l),
+              NULLIF(br.requested_lines->'bulk'->>'cargoWeightTons', '') || ' t',
+              NULLIF(br.requested_lines->'bulk'->>'itemCount', '') || ' items')
+            FROM freight.booking_requests br
+           WHERE br.created_booking_id = ${alias}.id
+             AND br.deleted_at IS NULL
+           ORDER BY br.created_at DESC
+           LIMIT 1)`;
+}
+
+/**
+ * Boxes declared on the shipment request. Pairs with the real container count:
+ * `Containers = 0` AND `Requested containers >= 1` is exactly the set awaiting
+ * completion.
+ */
+export function bookingRequestedContainerCountSql(alias = 'b'): string {
+  return `(SELECT COALESCE(SUM((l->>'quantity')::int), 0)
+             FROM freight.booking_requests br
+             CROSS JOIN LATERAL ${REQUESTED_CONTAINER_LINES} AS l
+            WHERE br.created_booking_id = ${alias}.id
+              AND br.deleted_at IS NULL)`;
+}

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

@@ -26,6 +26,7 @@ import {
   bookingContainerCountSql,
   bookingContentMatchSql,
   bookingHasContainerTypeSql,
+  bookingRequestedContainerCountSql,
 } from './booking-content.sql';
 import { BookingCargoModifier } from './entities/booking-cargo-modifier.entity';
 import {
@@ -79,6 +80,9 @@ export interface BookingListFilterOptions {
   containerTypeId?: string;
   containersMin?: number;
   containersMax?: number;
+  /** Bounds on containers declared on the shipment request behind the booking. */
+  requestedContainersMin?: number;
+  requestedContainersMax?: number;
   freightType?: string;
   bookingType?: string;
   tradeDirection?: string;
@@ -1225,6 +1229,19 @@ export class BookingsRepository extends BaseRepository<Booking> {
         });
       }
     }
+    // Declared on the shipment request, not on the booking. Pairs with the
+    // count above: containers 0..0 AND requested >= 1 is the set awaiting
+    // completion after clearance.
+    if (options.requestedContainersMin != null) {
+      qb.andWhere(`${bookingRequestedContainerCountSql('booking')} >= :requestedContainersMin`, {
+        requestedContainersMin: options.requestedContainersMin,
+      });
+    }
+    if (options.requestedContainersMax != null) {
+      qb.andWhere(`${bookingRequestedContainerCountSql('booking')} <= :requestedContainersMax`, {
+        requestedContainersMax: options.requestedContainersMax,
+      });
+    }
     if (omit !== 'freightType' && options.freightType) {
       qb.andWhere('booking.freight_type = :freightType', {
         freightType: options.freightType,

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

@@ -1849,6 +1849,8 @@ export class BookingsService {
       containerTypeId: filter.containerTypeId,
       containersMin: filter.containersMin,
       containersMax: filter.containersMax,
+      requestedContainersMin: filter.requestedContainersMin,
+      requestedContainersMax: filter.requestedContainersMax,
       freightType: filter.freightType,
       bookingType: filter.bookingType,
       tradeDirection: filter.tradeDirection,
@@ -2080,6 +2082,8 @@ export class BookingsService {
       containerTypeId: filter.containerTypeId,
       containersMin: filter.containersMin,
       containersMax: filter.containersMax,
+      requestedContainersMin: filter.requestedContainersMin,
+      requestedContainersMax: filter.requestedContainersMax,
       freightType: filter.freightType,
       bookingType: filter.bookingType,
       tradeDirection: filter.tradeDirection,

apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts

@@ -103,6 +103,19 @@ export class FilterBookingDto {
   @Transform(({ value }) => (value === '' || value == null ? undefined : Number(value)))
   containersMax?: number;
 
+  @ApiPropertyOptional({
+    description:
+      'Minimum containers declared on the shipment request behind the booking',
+  })
+  @IsOptional()
+  @Transform(({ value }) => (value === '' || value == null ? undefined : Number(value)))
+  requestedContainersMin?: number;
+
+  @ApiPropertyOptional({ description: 'Maximum requested containers — see requestedContainersMin' })
+  @IsOptional()
+  @Transform(({ value }) => (value === '' || value == null ? undefined : Number(value)))
+  requestedContainersMax?: number;
+
   @ApiPropertyOptional({ enum: FREIGHT_TYPES })
   @IsOptional()
   @IsIn([...FREIGHT_TYPES])