feat(bookings): two-level clearance charges (port + misc) billed to customer with invoices

packages/types/src/freight/index.ts

@@ -188,6 +188,11 @@ export enum InvoiceSource {
   LastMile = "lastmile",
   /** Customs clearance service fee — billed on the booking invoice with the freight. */
   Clearance = "clearance",
+  /**
+   * Post-finalization clearance charge (port charges / miscellaneous) billed
+   * to the customer as its own payable invoice. `sourceId` is the charge id.
+   */
+  ClearanceCharge = "clearance_charge",
   /**
    * A batch of shipping-line credits billed together. Unlike every other
    * source, `sourceId` is the shipping line's id rather than a single record's:
@@ -802,6 +807,40 @@ export interface PricingBreakdown {
 
 export type DocumentReviewStatus = "PENDING" | "APPROVED" | "QUERIED";
 
+// ── Clearance charges (post-finalization customer billing) ──────────────────
+
+export type ClearanceChargeType = "PORT_CHARGES" | "MISCELLANEOUS";
+
+/**
+ * DOC_UPLOADED: GL Djibouti uploaded the supporting document (port charges).
+ * BILLED: GL Ethiopia set amount + currency. SENT: invoice issued to the
+ * customer (ETB pays via gateway, other currencies via Finance's manual
+ * settlement). PAID: the invoice settled.
+ */
+export type ClearanceChargeStatus =
+  | "DOC_UPLOADED"
+  | "BILLED"
+  | "SENT"
+  | "PAID";
+
+/** One clearance charge level on a booking — at most one per type. */
+export interface ClearanceCharge {
+  id: string;
+  bookingId: string;
+  type: ClearanceChargeType;
+  status: ClearanceChargeStatus;
+  file: { id: string; name: string; url: string } | null;
+  amount: number | null;
+  currency: string | null;
+  invoiceId: string | null;
+  invoiceNumber: string | null;
+  uploadedByName: string | null;
+  uploadedAt: string | null;
+  billedByName: string | null;
+  billedAt: string | null;
+  paidAt: string | null;
+}
+
 /** One entry of a clearance document's audit trail, oldest first. */
 export interface ClearanceDocumentEvent {
   type: "UPLOADED" | "RESUBMITTED" | "QUERIED" | "APPROVED";