Merge branch 'alpha' of github.com:Tria-plc/edr-platform into alpha

packages/types/src/freight/contracts.ts

@@ -42,6 +42,7 @@ export const CONTRACT_STATUSES = [
   "FULLY_EXECUTED", // ONE_TIME
   "CONTRACT_ACTIVE", // GENERAL
   // customs clearance execution (Path B, pre-booking)
+  "AWAITING_CLEARANCE_PAYMENT", // clearance service fee invoiced, unpaid
   "AWAITING_CLEARANCE_DOCUMENTS",
   "CLEARANCE_UNDER_REVIEW",
   "CLEARANCE_READY_FOR_BOOKING",
@@ -67,6 +68,7 @@ export type ContractStatus = (typeof CONTRACT_STATUSES)[number];
  */
 export const CONTRACT_CLEARANCE_STATUSES = [
   "NOT_APPLICABLE",
+  "AWAITING_PAYMENT", // Path B — clearance service fee must be paid first
   "AWAITING_DOCUMENTS",
   "DOCUMENTS_UNDER_REVIEW",
   "CLEARANCE_READY_FOR_BOOKING", // Path B — GL may create the booking
@@ -102,6 +104,11 @@ export interface ContractUnitRateLineItem {
   /** "is_hazardous" | "is_reefer" when this is a conditional surcharge. */
   conditionalOn?: string | null;
   cargoTypeCode?: string | null;
+  /**
+   * True for the customs clearance service fee — billed separately in advance
+   * (before document upload), never part of shipment booking totals.
+   */
+  isClearance?: boolean;
 }
 
 /** Contract `pricing_breakdown` shape — unit rates, no totals. */
@@ -726,6 +733,11 @@ export interface CreateBookingContainerLineDto {
   quantity: number;
   hazardousQuantity?: number;
   reeferQuantity?: number;
+  /**
+   * How many units ship with empty-container return (≤ quantity). Only allowed
+   * when the contract was created WITH_RETURN (container freight only).
+   */
+  returnQuantity?: number;
   units: CreateContainerUnitDto[];
 }
 

packages/types/src/freight/index.ts

@@ -101,6 +101,8 @@ export enum BookingStatus {
   PendingConsolidation = "PENDING_CONSOLIDATION",
   Consolidated = "CONSOLIDATED",
   // Post counter-sign document-clearance gate (GL workflow).
+  /** Clearance service fee invoiced; docs + GL work locked until paid. */
+  AwaitingClearancePayment = "AWAITING_CLEARANCE_PAYMENT",
   AwaitingDocuments = "AWAITING_DOCUMENTS",
   DocumentsUnderReview = "DOCUMENTS_UNDER_REVIEW",
   ClearanceReady = "CLEARANCE_READY",
@@ -173,7 +175,9 @@ export enum InvoiceSource {
   Warehouse = "warehouse",
   Demurrage = "demurrage",
   FirstMile = "firstmile",
-  LastMile = "lastmile"
+  LastMile = "lastmile",
+  /** Customs clearance service fee, prepaid before clearance work begins. */
+  Clearance = "clearance"
 }
 
 export enum SchedulingStatus {