@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/lib/carrier-adapter.ts

@@ -0,0 +1,136 @@
+import type { TrackingEventType, TrackingEventClassifierCode, TrackingEventSource, TrackingReferenceType } from '../data/entities'
+import type { SealInfo } from './route-extraction'
+
+export type { SealInfo } from './route-extraction'
+
+export type DocumentReference = {
+  type: string // BKG, TRD, SHI, CBR, ARN, VGM, etc.
+  value: string
+}
+
+export type CarrierFetchedEvent = {
+  // ─── Event Source ──────────────────────────────────────────────
+  source: TrackingEventSource
+  sourceEventId: string // Original ID from the source system (e.g., DCSA eventId)
+
+  // ─── Core Event Fields ─────────────────────────────────────────
+  eventType: TrackingEventType
+  eventCode: string
+  eventClassifierCode?: TrackingEventClassifierCode | null
+  eventDateTime: Date
+  eventDateTimeOffset?: string | null
+  description?: string | null
+  rawData?: Record<string, unknown> | null
+
+  // ─── Equipment Fields (DCSA EQUIPMENT events) ──────────────────
+  equipmentReference?: string | null // Container number (BIC ISO)
+  isoEquipmentCode?: string | null // Container type (22G1, 45R1, etc.)
+  emptyIndicatorCode?: 'EMPTY' | 'LADEN' | null
+  isTransshipmentMove?: boolean | null
+
+  // ─── Location Fields ───────────────────────────────────────────
+  locationName?: string | null
+  locationUnlocode?: string | null
+  locationCountry?: string | null
+  facilityCode?: string | null // Terminal/depot code (SMDG/BIC)
+  facilityCodeListProvider?: 'SMDG' | 'BIC' | null
+  facilityTypeCode?: string | null // POTE, DEPO, CLOC, COFS, etc.
+  facilityAddress?: string | null // Full address string (from DCSA otherFacility)
+  latitude?: number | null
+  longitude?: number | null
+
+  // ─── Transport Call Fields ─────────────────────────────────────
+  transportCallReference?: string | null
+  modeOfTransport?: 'VESSEL' | 'RAIL' | 'TRUCK' | 'BARGE' | 'AIR' | null
+  vesselName?: string | null
+  vesselImo?: string | null
+  voyageNumber?: string | null
+  carrierServiceCode?: string | null
+  carrierExportVoyageNumber?: string | null
+  carrierImportVoyageNumber?: string | null
+  universalServiceReference?: string | null
+  universalExportVoyageReference?: string | null
+  universalImportVoyageReference?: string | null
+  portVisitReference?: string | null
+
+  // ─── Document References ───────────────────────────────────────
+  relatedDocumentReferences?: DocumentReference[] | null
+
+  // ─── Metadata Fields ───────────────────────────────────────────
+  eventCreatedDateTime?: Date | null
+  retractedEventId?: string | null
+  publisherName?: string | null
+  publisherRole?: string | null // CA, AG, VSL, TR, etc.
+
+  // ─── Additional Event Fields ───────────────────────────────────
+  delayReasonCode?: string | null // SMDG delay reason code
+  changeRemark?: string | null
+  seals?: SealInfo[] | null
+}
+
+export type CarrierAdapterTestResult = {
+  success: boolean
+  message: string
+  latencyMs?: number
+}
+
+export type CarrierFetchResult = {
+  events: CarrierFetchedEvent[]
+  containerNumber?: string | null
+  bookingNumber?: string | null
+  bolNumber?: string | null
+  vesselName?: string | null
+  vesselImo?: string | null
+  // ─── Air (mode='air') ──────────────────────────────────────────
+  // Air shipments have no container/vessel; identity is the AWB + flight/airline.
+  awbNumber?: string | null
+  flightNumber?: string | null
+  airlineCode?: string | null
+  airlineName?: string | null
+  /** ShipsGo top-level air status (NEW/BOOKED/EN_ROUTE/LANDED/DELIVERED/…). */
+  airStatus?: string | null
+  /**
+   * Provider shipment-level metadata that has no dedicated column — merged into
+   * `Shipment.extra`. Ocean: ShipsGo route summary (POL/POD + dates, transit
+   * time, CO2, transshipments). Air: cargo (pieces/weight/volume) + status_extended.
+   */
+  extra?: Record<string, unknown> | null
+}
+
+/**
+ * Extracts booking and BOL numbers from DCSA document references across all events.
+ * BKG = Booking reference, TRD/SHI = Transport Document / Shipping Instruction (BOL).
+ */
+export function extractDocumentReferences(events: CarrierFetchedEvent[]): {
+  bookingNumber: string | null
+  bolNumber: string | null
+} {
+  let bookingNumber: string | null = null
+  let bolNumber: string | null = null
+  for (const event of events) {
+    if (!event.relatedDocumentReferences) continue
+    for (const ref of event.relatedDocumentReferences) {
+      if (!bookingNumber && ref.type === 'BKG' && ref.value) bookingNumber = ref.value
+      if (!bolNumber && (ref.type === 'TRD' || ref.type === 'SHI') && ref.value) bolNumber = ref.value
+      if (bookingNumber && bolNumber) return { bookingNumber, bolNumber }
+    }
+  }
+  return { bookingNumber, bolNumber }
+}
+
+export interface CarrierAdapter {
+  readonly carrierCode: string
+  readonly supportedReferenceTypes: TrackingReferenceType[]
+
+  fetchEvents(input: {
+    referenceType: TrackingReferenceType
+    referenceValue: string
+    apiEndpoint?: string | null
+    authConfig?: Record<string, unknown> | null
+  }): Promise<CarrierFetchResult>
+
+  testConnection(input: {
+    apiEndpoint?: string | null
+    authConfig?: Record<string, unknown> | null
+  }): Promise<CarrierAdapterTestResult>
+}

package/src/modules/shipment_tracking/lib/current-vessel.ts

@@ -0,0 +1,274 @@
+/**
+ * Current vessel derivation utilities for shipment tracking.
+ *
+ * Determines which vessel the container is currently on (or waiting for)
+ * based on shipment progress through route stops.
+ */
+
+import type { RouteStopEntry, CargoEventEntry } from './route-extraction'
+
+// ─── Types ───────────────────────────────────────────────────
+
+/**
+ * Container's current tracking status.
+ */
+export type VesselTrackingStatus =
+  | 'in_transit'    // Container is on a vessel moving between ports
+  | 'at_port'       // Container is at a port (waiting for next vessel or just arrived)
+  | 'not_departed'  // Container hasn't started journey yet (at origin)
+  | 'delivered'     // Container has arrived at final destination
+
+/**
+ * Information about the current or planned vessel for tracking.
+ */
+export interface CurrentVesselInfo {
+  /** Current or planned vessel name */
+  vesselName: string | null
+  /** Current or planned vessel IMO for tracking */
+  vesselImo: string | null
+  /** Container's current status */
+  status: VesselTrackingStatus
+  /** Current leg info (if in transit) */
+  currentLeg?: {
+    fromPort: string
+    toPort: string
+  }
+  /** Port name where container currently is (if at_port or not_departed) */
+  currentPort?: string
+  /** Whether the vessel shown is planned (not yet departed) vs currently carrying container */
+  isPlannedVessel: boolean
+  /** Start date for trace - ATD from departure port (in_transit) or 7 days ago (planned) */
+  traceFrom?: string
+}
+
+// ─── Helper Functions ────────────────────────────────────────
+
+/**
+ * Returns ISO 8601 date string for 7 days ago.
+ * Used as default trace start time for planned vessels.
+ */
+function getSevenDaysAgo(): string {
+  const date = new Date()
+  date.setDate(date.getDate() - 7)
+  return date.toISOString()
+}
+
+// ─── Helper Functions ────────────────────────────────────────
+
+/**
+ * Finds the last vessel that carried the container by searching route stops backwards.
+ * Used for delivered shipments to show which vessel completed the journey.
+ */
+function findLastVesselFromStops(
+  routeStops: RouteStopEntry[],
+  cargoEvents: CargoEventEntry[] | null | undefined
+): { vesselName: string | null; vesselImo: string | null } {
+  // Work backwards from the last stop to find a stop with vessel info
+  for (let i = routeStops.length - 1; i >= 0; i--) {
+    const stop = routeStops[i]
+    if (stop.vesselName) {
+      const vesselImo = stop.vesselImo || findVesselImoFromEvents(stop.vesselName, cargoEvents)
+      return { vesselName: stop.vesselName, vesselImo }
+    }
+  }
+  return { vesselName: null, vesselImo: null }
+}
+
+// ─── Main Function ───────────────────────────────────────────
+
+/**
+ * Determines the current vessel based on shipment progress through route stops.
+ *
+ * Algorithm:
+ * 1. If final destination has ATA → Container delivered, no vessel to track
+ * 2. Find the latest stop with ATD where next stop doesn't have ATA
+ *    → Container is in transit on this leg's vessel
+ * 3. Find stop with ATA but no ATD (container at port waiting)
+ *    → Return next leg's planned vessel if available
+ * 4. No stops have ATD → Container not departed yet
+ *    → Return first leg's planned vessel
+ *
+ * @param routeStops - Array of route stops from shipment
+ * @param cargoEvents - Array of cargo events (used to find vessel IMO if not in stops)
+ * @param fallbackVessel - Fallback vessel info from shipment entity
+ * @returns CurrentVesselInfo with vessel details and status
+ */
+export function getCurrentVessel(
+  routeStops: RouteStopEntry[] | null | undefined,
+  cargoEvents: CargoEventEntry[] | null | undefined,
+  fallbackVessel?: { vesselName?: string | null; vesselImo?: string | null }
+): CurrentVesselInfo {
+  // Default result when no data available
+  const defaultResult: CurrentVesselInfo = {
+    vesselName: fallbackVessel?.vesselName ?? null,
+    vesselImo: fallbackVessel?.vesselImo ?? null,
+    status: 'not_departed',
+    isPlannedVessel: true,
+    traceFrom: getSevenDaysAgo(),
+  }
+
+  if (!routeStops || routeStops.length === 0) {
+    return defaultResult
+  }
+
+  // Check if container is delivered (final destination has ATA)
+  const destination = routeStops.find((s) => s.type === 'destination')
+  if (destination?.ata) {
+    // Find the last vessel that carried the container (for display purposes)
+    // Work backwards from destination to find a stop with vessel info
+    const lastVesselInfo = findLastVesselFromStops(routeStops, cargoEvents)
+    return {
+      vesselName: lastVesselInfo.vesselName,
+      vesselImo: lastVesselInfo.vesselImo,
+      status: 'delivered',
+      currentPort: destination.location,
+      isPlannedVessel: false,
+      // No traceFrom needed for delivered containers (map not shown)
+    }
+  }
+
+  // Find where the container currently is
+  // Look for the latest stop with ATD where the next stop doesn't have ATA yet
+  for (let i = routeStops.length - 1; i >= 0; i--) {
+    const stop = routeStops[i]
+    const nextStop = routeStops[i + 1]
+
+    // Case 1: Stop has ATD and next stop exists but doesn't have ATA
+    // → Container is in transit between these stops
+    if (stop.atd && nextStop && !nextStop.ata) {
+      const vesselImo = stop.vesselImo || findVesselImoFromEvents(stop.vesselName, cargoEvents) || fallbackVessel?.vesselImo || null
+      return {
+        vesselName: stop.vesselName ?? null,
+        vesselImo,
+        status: 'in_transit',
+        currentLeg: {
+          fromPort: stop.location,
+          toPort: nextStop.location,
+        },
+        isPlannedVessel: false,
+        traceFrom: stop.atd,  // Use ATD from departure port
+      }
+    }
+
+    // Case 2: Stop has ATA but no ATD (container is at this port)
+    // → Return the next leg's vessel as planned vessel
+    if (stop.ata && !stop.atd) {
+      // Look for next stop's vessel
+      if (nextStop) {
+        const vesselImo =
+          nextStop.vesselImo || findVesselImoFromEvents(nextStop.vesselName, cargoEvents) || fallbackVessel?.vesselImo || null
+        return {
+          vesselName: nextStop.vesselName ?? null,
+          vesselImo,
+          status: 'at_port',
+          currentPort: stop.location,
+          isPlannedVessel: true,
+          traceFrom: getSevenDaysAgo(),  // Last 7 days for planned vessel
+        }
+      }
+      // At final stop but no ATA on destination (shouldn't happen normally)
+      return {
+        vesselName: null,
+        vesselImo: null,
+        status: 'at_port',
+        currentPort: stop.location,
+        isPlannedVessel: false,
+        traceFrom: getSevenDaysAgo(),
+      }
+    }
+  }
+
+  // Case 3: No stops have ATD → Container hasn't departed yet
+  // Return first leg's vessel as planned
+  const origin = routeStops[0]
+  const vesselImo = origin?.vesselImo || findVesselImoFromEvents(origin?.vesselName, cargoEvents)
+
+  return {
+    vesselName: origin?.vesselName ?? fallbackVessel?.vesselName ?? null,
+    vesselImo: vesselImo ?? fallbackVessel?.vesselImo ?? null,
+    status: 'not_departed',
+    currentPort: origin?.location,
+    isPlannedVessel: true,
+    traceFrom: getSevenDaysAgo(),  // Last 7 days for planned vessel
+  }
+}
+
+// ─── More Helper Functions ───────────────────────────────────
+
+/**
+ * Find vessel IMO from cargo events by vessel name.
+ * Used when RouteStopEntry only has vesselName but needs IMO.
+ *
+ * @param vesselName - Vessel name to search for
+ * @param events - Array of cargo events
+ * @returns Vessel IMO if found, null otherwise
+ */
+export function findVesselImoFromEvents(
+  vesselName: string | null | undefined,
+  events: CargoEventEntry[] | null | undefined
+): string | null {
+  if (!vesselName || !events || events.length === 0) {
+    return null
+  }
+
+  // Find any event with matching vessel name that has an IMO
+  const eventWithImo = events.find(
+    (e) => e.vesselName === vesselName && e.vesselImo
+  )
+
+  return eventWithImo?.vesselImo ?? null
+}
+
+/**
+ * Get a human-readable description of the current vessel status.
+ * Useful for UI display.
+ *
+ * @param info - Current vessel info
+ * @returns Status description object with keys for i18n
+ */
+export function getVesselStatusDescription(info: CurrentVesselInfo): {
+  key: string
+  params?: Record<string, string>
+} {
+  switch (info.status) {
+    case 'in_transit':
+      return {
+        key: 'shipment_tracking.map.inTransit',
+        params: {
+          destination: info.currentLeg?.toPort ?? '',
+        },
+      }
+    case 'at_port':
+      if (info.vesselName) {
+        return {
+          key: 'shipment_tracking.map.atPortAwaitingVessel',
+          params: {
+            port: info.currentPort ?? '',
+            vessel: info.vesselName,
+          },
+        }
+      }
+      return {
+        key: 'shipment_tracking.map.atPort',
+        params: {
+          port: info.currentPort ?? '',
+        },
+      }
+    case 'not_departed':
+      if (info.vesselName) {
+        return {
+          key: 'shipment_tracking.map.awaitingDeparture',
+          params: {
+            vessel: info.vesselName,
+          },
+        }
+      }
+      return {
+        key: 'shipment_tracking.map.notDeparted',
+      }
+    case 'delivered':
+      return {
+        key: 'shipment_tracking.map.delivered',
+      }
+  }
+}

package/src/modules/shipment_tracking/lib/dcsa-event-mapping.ts

@@ -0,0 +1,202 @@
+import type { TrackingEventType, TrackingEventClassifierCode } from '../data/entities'
+
+/**
+ * DCSA Track & Trace Event Code Mapping
+ *
+ * Maps DCSA standard event codes to internal webhook event types.
+ * Reference: DCSA T&T v3.0 specification
+ *
+ * Event Types:
+ * - TRANSPORT: Vessel/transport movement events (ARRI, DEPA, OMIT)
+ * - EQUIPMENT: Container handling events (LOAD, DISC, GTIN, GTOT, etc.)
+ * - SHIPMENT: Document lifecycle events (not typically from carrier tracking)
+ *
+ * Event Classifiers:
+ * - ACT: Actual (event has happened)
+ * - PLN: Planned
+ * - EST: Estimated
+ */
+
+export type DcsaWebhookEventType =
+  // Transport events
+  | 'shipment_tracking.transport.departed'
+  | 'shipment_tracking.transport.arrived'
+  | 'shipment_tracking.transport.eta_updated'
+  | 'shipment_tracking.transport.etd_updated'
+  | 'shipment_tracking.transport.omitted'
+  // Equipment events
+  | 'shipment_tracking.equipment.loaded'
+  | 'shipment_tracking.equipment.discharged'
+  | 'shipment_tracking.equipment.gate_in'
+  | 'shipment_tracking.equipment.gate_out'
+  | 'shipment_tracking.equipment.available_pickup'
+  | 'shipment_tracking.equipment.customs_released'
+  | 'shipment_tracking.equipment.inspected'
+  // Shipment lifecycle
+  | 'shipment_tracking.shipment.booked'
+  | 'shipment_tracking.shipment.delivered'
+  // Generic fallback
+  | 'shipment_tracking.tracking_event.created'
+
+export type EventMappingInput = {
+  eventType: TrackingEventType
+  eventCode: string
+  eventClassifierCode?: TrackingEventClassifierCode | null
+}
+
+/**
+ * Maps a DCSA cargo event to the appropriate webhook event type.
+ *
+ * @param input - The cargo event details from carrier API
+ * @returns The internal webhook event type to emit
+ */
+export function mapDcsaEventToWebhookType(input: EventMappingInput): DcsaWebhookEventType {
+  const { eventType, eventCode, eventClassifierCode } = input
+  const code = eventCode.toUpperCase()
+  const isActual = eventClassifierCode === 'ACT'
+  const isEstimatedOrPlanned = eventClassifierCode === 'EST' || eventClassifierCode === 'PLN'
+
+  // ─── Transport Events ──────────────────────────────────────────
+  if (eventType === 'TRANSPORT') {
+    switch (code) {
+      case 'DEPA': // Departure
+        if (isActual) return 'shipment_tracking.transport.departed'
+        if (isEstimatedOrPlanned) return 'shipment_tracking.transport.etd_updated'
+        return 'shipment_tracking.transport.etd_updated' // Default to ETD update
+      case 'ARRI': // Arrival
+        if (isActual) return 'shipment_tracking.transport.arrived'
+        if (isEstimatedOrPlanned) return 'shipment_tracking.transport.eta_updated'
+        return 'shipment_tracking.transport.eta_updated' // Default to ETA update
+      case 'OMIT': // Port omitted
+        return 'shipment_tracking.transport.omitted'
+    }
+  }
+
+  // ─── Equipment Events ──────────────────────────────────────────
+  if (eventType === 'EQUIPMENT') {
+    switch (code) {
+      // Loading/Discharge
+      case 'LOAD': // Loaded onto vessel
+        return 'shipment_tracking.equipment.loaded'
+      case 'DISC': // Discharged from vessel
+        return 'shipment_tracking.equipment.discharged'
+
+      // Gate movements
+      case 'GTIN': // Gate in
+        return 'shipment_tracking.equipment.gate_in'
+      case 'GTOT': // Gate out (terminal)
+        return 'shipment_tracking.equipment.gate_out'
+
+      // Availability
+      case 'AVPU': // Available for pick-up
+        return 'shipment_tracking.equipment.available_pickup'
+      case 'AVDO': // Available for drop-off (less common, map to gate_in context)
+        return 'shipment_tracking.equipment.gate_in'
+
+      // Customs
+      case 'CUSR': // Customs released
+        return 'shipment_tracking.equipment.customs_released'
+      case 'CUSS': // Customs selected for scan
+      case 'CUSI': // Customs selected for inspection
+        return 'shipment_tracking.equipment.inspected'
+
+      // Inspection
+      case 'INSP': // Inspected
+        return 'shipment_tracking.equipment.inspected'
+
+      // Delivery
+      case 'DLVR': // Delivered
+        if (isActual) return 'shipment_tracking.shipment.delivered'
+        break
+
+      // Pick-up/Drop-off (physical movement)
+      case 'PICK': // Pick-up
+        return 'shipment_tracking.equipment.gate_out'
+      case 'DROP': // Drop-off
+        return 'shipment_tracking.equipment.gate_in'
+
+      // Stuffing/Stripping
+      case 'STUF': // Stuffed (cargo loaded into container)
+      case 'STRP': // Stripped (cargo unloaded from container)
+        // These are container content events, map to generic
+        break
+
+      // Sealing
+      case 'RSEA': // Resealed
+      case 'RMVD': // Seal removed
+        // Seal events, map to generic
+        break
+
+      // Transshipment crossing
+      case 'CROS': // Crossed (transshipment)
+        // Map to discharge as it indicates container moved
+        return 'shipment_tracking.equipment.discharged'
+    }
+  }
+
+  // ─── Shipment Events ───────────────────────────────────────────
+  if (eventType === 'SHIPMENT') {
+    // Shipment events are typically document-related (booking, BL issuance)
+    // These come from different APIs, not container tracking
+    // Map common booking-related codes
+    switch (code) {
+      case 'CONF': // Confirmed
+      case 'BOOK': // Booked (non-standard but common)
+        return 'shipment_tracking.shipment.booked'
+    }
+  }
+
+  // ─── Fallback ──────────────────────────────────────────────────
+  return 'shipment_tracking.tracking_event.created'
+}
+
+/**
+ * Determines if a tracking event represents a significant milestone
+ * that warrants a specific webhook event (vs generic tracking_event.created).
+ */
+export function isSignificantMilestone(input: EventMappingInput): boolean {
+  const webhookType = mapDcsaEventToWebhookType(input)
+  return webhookType !== 'shipment_tracking.tracking_event.created'
+}
+
+/**
+ * DCSA Equipment Event Type Codes reference
+ */
+export const DCSA_EQUIPMENT_EVENT_CODES = {
+  LOAD: 'Loaded onto transport',
+  DISC: 'Discharged from transport',
+  GTIN: 'Gated in (entered facility)',
+  GTOT: 'Gated out (terminal)',
+  STUF: 'Stuffed (cargo loaded into container)',
+  STRP: 'Stripped (cargo removed from container)',
+  PICK: 'Pick-up by consignee/trucker',
+  DROP: 'Drop-off at facility',
+  INSP: 'Inspected',
+  RSEA: 'Resealed',
+  RMVD: 'Seal removed',
+  AVPU: 'Available for pick-up',
+  AVDO: 'Available for drop-off',
+  CUSS: 'Customs selected for scan',
+  CUSI: 'Customs selected for inspection',
+  CUSR: 'Customs released',
+  CROS: 'Crossed (transshipment)',
+  DLVR: 'Delivered to consignee',
+} as const
+
+/**
+ * DCSA Transport Event Type Codes reference
+ */
+export const DCSA_TRANSPORT_EVENT_CODES = {
+  ARRI: 'Arrived at location',
+  DEPA: 'Departed from location',
+  OMIT: 'Port/location omitted from schedule',
+} as const
+
+/**
+ * DCSA Event Classifier Codes reference
+ */
+export const DCSA_EVENT_CLASSIFIERS = {
+  ACT: 'Actual (event has occurred)',
+  PLN: 'Planned',
+  EST: 'Estimated',
+} as const