@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/lib/shipsgo-mapper.ts

@@ -0,0 +1,296 @@
+/**
+ * Maps ShipsGo shipment responses into the internal `CarrierFetchResult` shape,
+ * so the existing ingestion pipeline (Shipment upsert, timestamps, status
+ * machine, route inference, unit-sync) consumes ShipsGo exactly like a DCSA
+ * carrier adapter.
+ *
+ * Ocean movement codes are translated onto the DCSA equipment/transport
+ * vocabulary the downstream event-mapping already understands
+ * (see dcsa-event-mapping.ts), so notifier events resolve unchanged.
+ */
+import type { CarrierFetchResult, CarrierFetchedEvent } from './carrier-adapter'
+import type {
+  TrackingEventType,
+  TrackingEventClassifierCode,
+  ModeOfTransport,
+} from '../data/entities'
+import type {
+  ShipsGoOceanContainer,
+  ShipsGoOceanMovement,
+  ShipsGoOceanShipment,
+  ShipsGoAirMovement,
+  ShipsGoAirShipment,
+} from './shipsgo-client'
+
+// ShipsGo ocean event → { internal DCSA-style eventType + eventCode }.
+// GTIN/LOAD/DISC/GTOT map 1:1; ARRV→ARRI (DCSA spelling); EMSH/EMRT use the
+// closest DCSA equipment code so the notifier resolves (pick-up / drop-off).
+const OCEAN_EVENT_MAP: Record<string, { eventType: TrackingEventType; eventCode: string }> = {
+  EMSH: { eventType: 'EQUIPMENT', eventCode: 'PICK' }, // empty released to shipper
+  GTIN: { eventType: 'EQUIPMENT', eventCode: 'GTIN' },
+  LOAD: { eventType: 'EQUIPMENT', eventCode: 'LOAD' },
+  DEPA: { eventType: 'TRANSPORT', eventCode: 'DEPA' },
+  ARRV: { eventType: 'TRANSPORT', eventCode: 'ARRI' },
+  DISC: { eventType: 'EQUIPMENT', eventCode: 'DISC' },
+  GTOT: { eventType: 'EQUIPMENT', eventCode: 'GTOT' },
+  EMRT: { eventType: 'EQUIPMENT', eventCode: 'DROP' }, // empty returned to depot
+}
+
+function classifier(status: 'EST' | 'ACT'): TrackingEventClassifierCode {
+  return status === 'ACT' ? 'ACT' : 'EST'
+}
+
+/**
+ * Deterministic id for dedup — ShipsGo movements have no stable identifier.
+ * ACT (actual) movements key on their timestamp (immutable once they happen);
+ * EST (estimated) movements OMIT the timestamp so a shifting estimate maps to
+ * the same row and is refreshed in place (see the persistence loop) rather than
+ * inserting a new event every poll.
+ */
+function movementId(container: string, m: ShipsGoOceanMovement): string {
+  const tsKey = m.status === 'EST' ? 'EST' : m.timestamp
+  return `${container}:${m.event}:${m.status}:${tsKey}`
+}
+
+function isLocode(code: string | null | undefined): boolean {
+  return typeof code === 'string' && /^[A-Z]{2}[A-Z0-9]{3}$/.test(code)
+}
+
+/**
+ * Extracts the local UTC offset from a ShipsGo ISO-8601 timestamp. ShipsGo dates
+ * carry the movement's local (port/airport) offset — e.g. `+08:00` for a Beijing
+ * departure — so `eventDateTime` (the UTC instant) alone loses the local wall
+ * clock the carrier reported. We persist the offset in `eventDateTimeOffset` for
+ * local-time display, matching the DCSA adapters. Returns null for UTC (`Z` or
+ * `+00:00`), which is already the default.
+ */
+function isoOffset(ts: string): string | null {
+  const match = ts.match(/([+-]\d{2}:\d{2})$/)
+  if (!match || match[1] === '+00:00') return null
+  return match[1]
+}
+
+/**
+ * ShipsGo container size (feet, e.g. 40) + type (e.g. HC, GP, RF) → a readable
+ * equipment code ("40HC"). Not a true ISO 6346 code, but it's the container-type
+ * display slot and ShipsGo doesn't return the ISO code. Null when neither given.
+ */
+function equipmentCode(container: ShipsGoOceanContainer): string | null {
+  const size = container.size != null ? String(container.size) : ''
+  const type = container.type ?? ''
+  const code = `${size}${type}`.trim()
+  return code || null
+}
+
+function mapOceanMovement(
+  container: ShipsGoOceanContainer,
+  m: ShipsGoOceanMovement,
+): CarrierFetchedEvent | null {
+  const mapping = OCEAN_EVENT_MAP[m.event]
+  if (!mapping) return null
+
+  const ts = new Date(m.timestamp)
+  if (Number.isNaN(ts.getTime())) return null
+
+  const loc = m.location
+  const hasVessel = Boolean(m.vessel?.name || m.vessel?.imo)
+
+  return {
+    source: 'shipsgo',
+    sourceEventId: movementId(container.number, m),
+    eventType: mapping.eventType,
+    eventCode: mapping.eventCode,
+    eventClassifierCode: classifier(m.status),
+    eventDateTime: ts,
+    eventDateTimeOffset: isoOffset(m.timestamp),
+    description: `ShipsGo ${m.event} (${m.status})`,
+    rawData: { provider: 'shipsgo', ...m },
+    equipmentReference: container.number,
+    isoEquipmentCode: equipmentCode(container),
+    locationName: loc?.name ?? null,
+    locationUnlocode: isLocode(loc?.code) ? loc?.code ?? null : null,
+    locationCountry: loc?.country?.code ?? null,
+    modeOfTransport: hasVessel ? ('VESSEL' as ModeOfTransport) : null,
+    vesselName: m.vessel?.name ?? null,
+    vesselImo: m.vessel?.imo != null ? String(m.vessel.imo) : null,
+    voyageNumber: m.voyage ?? null,
+  }
+}
+
+/**
+ * ShipsGo shipment-level route summary → a compact object for `Shipment.extra`.
+ * Origin/destination UNLOCODEs are already inferred from movement locations, so
+ * this captures the extras: POL/POD names + planned/predicted dates, transit
+ * time, transit %, transshipment count and CO2. Returns null when route is absent.
+ */
+function oceanRouteExtra(shipment: ShipsGoOceanShipment): Record<string, unknown> | null {
+  const route = shipment.route
+  if (!route) return null
+  const pol = route.port_of_loading
+  const pod = route.port_of_discharge
+  const extra: Record<string, unknown> = {}
+  if (pol?.location) extra.portOfLoading = { unlocode: pol.location.code ?? null, name: pol.location.name ?? null }
+  if (pol?.date_of_loading) extra.dateOfLoading = pol.date_of_loading
+  if (pod?.location) extra.portOfDischarge = { unlocode: pod.location.code ?? null, name: pod.location.name ?? null }
+  if (pod?.date_of_discharge) extra.dateOfDischarge = pod.date_of_discharge
+  if (pod?.date_of_discharge_predicted) extra.dateOfDischargePredicted = pod.date_of_discharge_predicted
+  if (route.transit_time != null) extra.transitTimeDays = route.transit_time
+  if (route.transit_percentage != null) extra.transitPercentage = route.transit_percentage
+  if (route.ts_count != null) extra.transshipmentCount = route.ts_count
+  if (route.co2_emission != null) extra.co2Emission = route.co2_emission
+  return Object.keys(extra).length ? { shipsgoRoute: extra } : null
+}
+
+/**
+ * Maps a full ShipsGo ocean shipment (with containers + movements) into a
+ * `CarrierFetchResult`. Emits one event per movement per container; the
+ * downstream pipeline discovers containers from `equipmentReference`.
+ */
+export function mapOceanShipmentToEvents(shipment: ShipsGoOceanShipment): CarrierFetchResult {
+  const events: CarrierFetchedEvent[] = []
+  let vesselName: string | null = null
+  let vesselImo: string | null = null
+
+  const containers = shipment.containers ?? []
+  for (const container of containers) {
+    const movements = container.movements ?? []
+    for (const m of movements) {
+      const event = mapOceanMovement(container, m)
+      if (!event) continue
+      events.push(event)
+      // Track the most recent vessel seen (movements are chronological).
+      if (event.vesselName) vesselName = event.vesselName
+      if (event.vesselImo) vesselImo = event.vesselImo
+    }
+  }
+
+  return {
+    events,
+    containerNumber: shipment.container_number ?? containers[0]?.number ?? null,
+    bookingNumber: shipment.booking_number ?? null,
+    bolNumber: null,
+    vesselName,
+    vesselImo,
+    extra: oceanRouteExtra(shipment),
+  }
+}
+
+// ─── Air ─────────────────────────────────────────────────────────────────────
+
+// ShipsGo air event → internal event code. DEP/ARR are translated to the DCSA
+// departure/arrival codes so the shared time-extraction (ATD/ATA) and timeline
+// reuse unchanged; the rest keep their native code (informational only — air
+// status is derived from ShipsGo's top-level status, see deriveAirShipmentStatus).
+const AIR_EVENT_MAP: Record<string, string> = {
+  RCS: 'RCS', // received from shipper
+  MAN: 'MAN', // manifested
+  DEP: 'DEPA', // departed
+  ARR: 'ARRI', // arrived
+  RCF: 'RCF', // received from flight
+  DLV: 'DLVR', // delivered
+}
+
+/** Deterministic id for dedup — air movements have no stable identifier.
+ * EST omits the timestamp (refreshed in place); ACT keys on it (immutable). */
+function airMovementId(awb: string, m: ShipsGoAirMovement): string {
+  const tsKey = m.status === 'EST' ? 'EST' : m.timestamp
+  return `${awb}:${m.event}:${m.status}:${tsKey}`
+}
+
+function mapAirMovement(awb: string, m: ShipsGoAirMovement): CarrierFetchedEvent | null {
+  const eventCode = AIR_EVENT_MAP[m.event]
+  if (!eventCode) return null
+
+  const ts = new Date(m.timestamp)
+  if (Number.isNaN(ts.getTime())) return null
+
+  const loc = m.location
+  return {
+    source: 'shipsgo',
+    sourceEventId: airMovementId(awb, m),
+    // Air movements are all transport-leg events (no container/equipment model).
+    eventType: 'TRANSPORT',
+    eventCode,
+    eventClassifierCode: classifier(m.status),
+    eventDateTime: ts,
+    eventDateTimeOffset: isoOffset(m.timestamp),
+    description: `ShipsGo air ${m.event} (${m.status})`,
+    rawData: { provider: 'shipsgo', mode: 'air', ...m },
+    // Air locations are IATA airports, not UN/LOCODEs — keep only the name/country.
+    locationName: loc?.name ?? loc?.iata ?? null,
+    locationUnlocode: null,
+    locationCountry: loc?.country?.code ?? null,
+    modeOfTransport: m.flight ? ('AIR' as ModeOfTransport) : null,
+  }
+}
+
+/**
+ * Maps a full ShipsGo air shipment into a `CarrierFetchResult`. Emits one event
+ * per movement (no container fan-out); the downstream air branch creates a
+ * single AWB-keyed Shipment and fills flight/airline + the top-level air status.
+ */
+export function mapAirShipmentToEvents(shipment: ShipsGoAirShipment): CarrierFetchResult {
+  const awb = shipment.awb_number ?? shipment.reference ?? ''
+  const events: CarrierFetchedEvent[] = []
+  let flightNumber: string | null = null
+
+  const movements = shipment.movements ?? []
+  for (const m of movements) {
+    const event = mapAirMovement(awb, m)
+    if (!event) continue
+    events.push(event)
+    // Track the most recent flight seen (movements are chronological).
+    if (m.flight) flightNumber = m.flight
+  }
+
+  return {
+    events,
+    containerNumber: null,
+    bookingNumber: null,
+    bolNumber: null,
+    awbNumber: shipment.awb_number ?? null,
+    flightNumber,
+    airlineCode: shipment.airline?.iata ?? null,
+    airlineName: shipment.airline?.name ?? null,
+    airStatus: shipment.status ?? null,
+    extra: airExtra(shipment),
+  }
+}
+
+/**
+ * ShipsGo air shipment-level extras → `Shipment.extra`: cargo (pieces/weight/
+ * volume) and the pieces-per-status breakdown. Returns null when neither given.
+ */
+function airExtra(shipment: ShipsGoAirShipment): Record<string, unknown> | null {
+  const extra: Record<string, unknown> = {}
+  const c = shipment.cargo
+  if (c && (c.pieces != null || c.weight != null || c.volume != null)) {
+    extra.cargo = {
+      pieces: c.pieces ?? null,
+      weight: c.weight ?? null,
+      weightUnit: c.weight_unit ?? null,
+      volume: c.volume ?? null,
+      volumeUnit: c.volume_unit ?? null,
+    }
+  }
+  // Air route mirrors the ocean route (see oceanRouteExtra). Air locations are
+  // IATA airports (not UN/LOCODEs), so event-based origin/destination inference
+  // yields nothing — this is the only place origin/destination surface for air.
+  const route = shipment.route
+  if (route) {
+    const r: Record<string, unknown> = {}
+    const orig = route.origin
+    const dest = route.destination
+    if (orig?.location) r.origin = { iata: orig.location.iata ?? null, name: orig.location.name ?? null }
+    if (orig?.date_of_dep) r.dateOfDeparture = orig.date_of_dep
+    if (dest?.location) r.destination = { iata: dest.location.iata ?? null, name: dest.location.name ?? null }
+    if (dest?.date_of_rcf) r.dateOfArrival = dest.date_of_rcf
+    if (route.transit_time != null) r.transitTimeDays = route.transit_time
+    if (route.transit_percentage != null) r.transitPercentage = route.transit_percentage
+    if (route.ts_count != null) r.transshipmentCount = route.ts_count
+    if (route.co2_emission != null) r.co2Emission = route.co2_emission
+    if (Object.keys(r).length) extra.route = r
+  }
+  if (shipment.status_extended != null) extra.statusExtended = shipment.status_extended
+  return Object.keys(extra).length ? { shipsgoAir: extra } : null
+}

package/src/modules/shipment_tracking/lib/status-machine.ts

@@ -0,0 +1,230 @@
+import type { ShipmentStatusEnum, TrackingEventClassifierCode } from '../data/entities'
+
+export type ShipmentStatus = ShipmentStatusEnum
+
+type EventInput = {
+  eventCode: string
+  eventClassifierCode?: TrackingEventClassifierCode | null
+  locationUnlocode?: string | null
+}
+
+type ShipmentContext = {
+  originUnlocode?: string | null
+  destinationUnlocode?: string | null
+}
+
+type TimeContext = {
+  eta?: Date | null
+  ata?: Date | null
+}
+
+/**
+ * Number of days before ETA when a shipment transitions to PRE_ARRIVAL status.
+ * Shipment becomes PRE_ARRIVAL when: ETA is within this many days AND no ATA yet.
+ */
+export const PRE_ARRIVAL_DAYS_THRESHOLD = 7
+
+const STATUS_ORDER: ShipmentStatus[] = [
+  'PENDING',
+  'BOOKED',
+  'DEPARTED',
+  'IN_TRANSIT',
+  'PRE_ARRIVAL',
+  'ARRIVED',
+  'DELIVERED',
+]
+
+function statusRank(status: ShipmentStatus): number {
+  return STATUS_ORDER.indexOf(status)
+}
+
+function isAtDestination(eventLocation: string | null | undefined, destination: string | null | undefined): boolean {
+  if (!eventLocation || !destination) return false
+  return eventLocation.toUpperCase() === destination.toUpperCase()
+}
+
+function isAtOrigin(eventLocation: string | null | undefined, origin: string | null | undefined): boolean {
+  if (!eventLocation || !origin) return false
+  return eventLocation.toUpperCase() === origin.toUpperCase()
+}
+
+function deriveStatusFromEvent(event: EventInput, context: ShipmentContext): ShipmentStatus | null {
+  const code = event.eventCode.toUpperCase()
+  const classifierCode = event.eventClassifierCode
+
+  // DEPA at origin = DEPARTED
+  if (code === 'DEPA') {
+    if (classifierCode === 'ACT') {
+      return 'DEPARTED'
+    }
+    if (classifierCode === 'PLN' || classifierCode === 'EST') {
+      return 'BOOKED'
+    }
+  }
+
+  // ARRI at destination = ARRIVED (actual) or IN_TRANSIT (planned/estimated approaching)
+  if (code === 'ARRI' && isAtDestination(event.locationUnlocode, context.destinationUnlocode)) {
+    if (classifierCode === 'ACT') {
+      return 'ARRIVED'
+    }
+    return 'IN_TRANSIT'
+  }
+
+  // ARRI at non-destination with actual = IN_TRANSIT (transshipment)
+  if (code === 'ARRI' && classifierCode === 'ACT') {
+    return 'IN_TRANSIT'
+  }
+
+  // DISC (discharge) at destination = ARRIVED
+  if (code === 'DISC' && isAtDestination(event.locationUnlocode, context.destinationUnlocode)) {
+    if (classifierCode === 'ACT') {
+      return 'ARRIVED'
+    }
+  }
+
+  // LOAD at origin = BOOKED (loaded onto vessel)
+  if (code === 'LOAD' && isAtOrigin(event.locationUnlocode, context.originUnlocode)) {
+    if (classifierCode === 'ACT') {
+      return 'BOOKED'
+    }
+  }
+
+  // Gate out at destination = DELIVERED (GTOT = Gate Out Terminal, PICK = Pick-up)
+  if ((code === 'GTOT' || code === 'PICK') && isAtDestination(event.locationUnlocode, context.destinationUnlocode)) {
+    if (classifierCode === 'ACT') {
+      return 'DELIVERED'
+    }
+  }
+
+  // Gate in at destination = DELIVERED (empty return means cargo was delivered)
+  if (code === 'GTIN' && isAtDestination(event.locationUnlocode, context.destinationUnlocode)) {
+    if (classifierCode === 'ACT') {
+      return 'DELIVERED'
+    }
+  }
+
+  // Available for pick-up at destination = ARRIVED
+  if (code === 'AVPU' && isAtDestination(event.locationUnlocode, context.destinationUnlocode)) {
+    if (classifierCode === 'ACT') {
+      return 'ARRIVED'
+    }
+  }
+
+  // Customs released at destination = ARRIVED
+  if (code === 'CUSR' && isAtDestination(event.locationUnlocode, context.destinationUnlocode)) {
+    if (classifierCode === 'ACT') {
+      return 'ARRIVED'
+    }
+  }
+
+  // Delivery event = DELIVERED
+  if (code === 'DLVR' && classifierCode === 'ACT') {
+    return 'DELIVERED'
+  }
+
+  return null
+}
+
+/**
+ * Checks if a shipment qualifies for PRE_ARRIVAL status based on time.
+ * PRE_ARRIVAL = ETA is within threshold days AND no ATA yet.
+ */
+function shouldUpgradeToPreArrival(timeContext: TimeContext | undefined): boolean {
+  if (!timeContext?.eta || timeContext.ata) {
+    return false
+  }
+
+  const now = new Date()
+  const daysUntilEta = (timeContext.eta.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
+
+  return daysUntilEta <= PRE_ARRIVAL_DAYS_THRESHOLD && daysUntilEta >= 0
+}
+
+/**
+ * Derives the highest-priority shipment status from a set of tracking events.
+ * Status only moves forward (never downgrades), based on DCSA event codes.
+ *
+ * @param events - Array of tracking events to evaluate
+ * @param context - Location context (origin/destination UNLOCODEs)
+ * @param currentStatus - Current shipment status (defaults to PENDING)
+ * @param timeContext - Optional time context for PRE_ARRIVAL evaluation (ETA/ATA)
+ */
+export function deriveShipmentStatus(
+  events: EventInput[],
+  context: ShipmentContext,
+  currentStatus: ShipmentStatus = 'PENDING',
+  timeContext?: TimeContext,
+): ShipmentStatus {
+  let best = currentStatus
+
+  for (const event of events) {
+    const derived = deriveStatusFromEvent(event, context)
+    if (derived && statusRank(derived) > statusRank(best)) {
+      best = derived
+    }
+  }
+
+  // Time-based PRE_ARRIVAL upgrade:
+  // If event-derived status is IN_TRANSIT (or lower) and time conditions are met,
+  // upgrade to PRE_ARRIVAL
+  if (statusRank(best) <= statusRank('IN_TRANSIT') && shouldUpgradeToPreArrival(timeContext)) {
+    const preArrivalRank = statusRank('PRE_ARRIVAL')
+    if (preArrivalRank > statusRank(best)) {
+      best = 'PRE_ARRIVAL'
+    }
+  }
+
+  return best
+}
+
+/**
+ * ShipsGo air top-level status → internal ShipmentStatusEnum.
+ * Air has no container/vessel movement model, so status is driven by ShipsGo's
+ * aggregate `status` field rather than event-location matching:
+ *   NEW/UNTRACKED → PENDING, BOOKED → BOOKED, EN_ROUTE → IN_TRANSIT,
+ *   LANDED → ARRIVED, DELIVERED → DELIVERED. (INPROGRESS ≈ BOOKED.)
+ * Monotonic: never downgrades below the current status.
+ */
+const AIR_STATUS_MAP: Record<string, ShipmentStatus> = {
+  NEW: 'PENDING',
+  UNTRACKED: 'PENDING',
+  INPROGRESS: 'BOOKED',
+  BOOKED: 'BOOKED',
+  EN_ROUTE: 'IN_TRANSIT',
+  LANDED: 'ARRIVED',
+  DELIVERED: 'DELIVERED',
+}
+
+export function deriveAirShipmentStatus(
+  airStatus: string | null | undefined,
+  currentStatus: ShipmentStatus = 'PENDING',
+): ShipmentStatus {
+  if (!airStatus) return currentStatus
+  const mapped = AIR_STATUS_MAP[airStatus.toUpperCase()]
+  if (!mapped) return currentStatus
+  return statusRank(mapped) > statusRank(currentStatus) ? mapped : currentStatus
+}
+
+/**
+ * Evaluates if a shipment should be upgraded to PRE_ARRIVAL status.
+ * Used by the scheduled job to check IN_TRANSIT shipments.
+ *
+ * @param currentStatus - Current shipment status
+ * @param timeContext - Time context with ETA and ATA
+ * @returns The new status (PRE_ARRIVAL if conditions met, otherwise currentStatus)
+ */
+export function evaluatePreArrivalUpgrade(
+  currentStatus: ShipmentStatus,
+  timeContext: TimeContext,
+): ShipmentStatus {
+  // Only upgrade from IN_TRANSIT to PRE_ARRIVAL
+  if (currentStatus !== 'IN_TRANSIT') {
+    return currentStatus
+  }
+
+  if (shouldUpgradeToPreArrival(timeContext)) {
+    return 'PRE_ARRIVAL'
+  }
+
+  return currentStatus
+}

package/src/modules/shipment_tracking/lib/time-extraction.ts

@@ -0,0 +1,85 @@
+import type { TrackingEventClassifierCode } from '../data/entities'
+
+type EventInput = {
+  eventCode: string
+  eventClassifierCode?: TrackingEventClassifierCode | null
+  eventDateTime: Date
+  eventDateTimeOffset?: string | null
+  eventCreatedDateTime?: Date | null
+  locationUnlocode?: string | null
+}
+
+type ShipmentContext = {
+  originUnlocode?: string | null
+  destinationUnlocode?: string | null
+}
+
+export type ExtractedTimes = {
+  etd?: Date | null
+  etdOffset?: string | null
+  eta?: Date | null
+  etaOffset?: string | null
+  atd?: Date | null
+  atdOffset?: string | null
+  ata?: Date | null
+  ataOffset?: string | null
+}
+
+function isAtLocation(eventLocation: string | null | undefined, target: string | null | undefined): boolean {
+  if (!eventLocation || !target) return false
+  return eventLocation.toUpperCase() === target.toUpperCase()
+}
+
+/**
+ * Extracts ETD/ETA/ATD/ATA from cargo events.
+ *
+ * Logic:
+ * - DEPA ACT at origin -> ATD
+ * - DEPA PLN/EST at origin -> ETD
+ * - ARRI ACT at destination -> ATA
+ * - ARRI PLN/EST at destination -> ETA
+ *
+ * When multiple events match the same field, the latest one wins.
+ * For EST/PLN events, we use eventCreatedDateTime (when estimate was published)
+ * to ensure revised estimates supersede earlier ones.
+ */
+export function extractShipmentTimes(events: EventInput[], context: ShipmentContext): ExtractedTimes {
+  const result: ExtractedTimes = {}
+
+  // Sort events by createdDateTime (when published) if available, else eventDateTime
+  // This ensures revised estimates (published later) supersede earlier ones
+  const sorted = [...events].sort((eventA, eventB) => {
+    const timeA = eventA.eventCreatedDateTime?.getTime() ?? eventA.eventDateTime.getTime()
+    const timeB = eventB.eventCreatedDateTime?.getTime() ?? eventB.eventDateTime.getTime()
+    return timeA - timeB
+  })
+
+  for (const event of sorted) {
+    const code = event.eventCode.toUpperCase()
+    const classifierCode = event.eventClassifierCode
+    const atOrigin = isAtLocation(event.locationUnlocode, context.originUnlocode)
+    const atDestination = isAtLocation(event.locationUnlocode, context.destinationUnlocode)
+
+    if (code === 'DEPA') {
+      if (classifierCode === 'ACT' && (atOrigin || !context.originUnlocode)) {
+        result.atd = event.eventDateTime
+        result.atdOffset = event.eventDateTimeOffset ?? null
+      } else if ((classifierCode === 'PLN' || classifierCode === 'EST') && (atOrigin || !context.originUnlocode)) {
+        result.etd = event.eventDateTime
+        result.etdOffset = event.eventDateTimeOffset ?? null
+      }
+    }
+
+    if (code === 'ARRI') {
+      if (classifierCode === 'ACT' && (atDestination || !context.destinationUnlocode)) {
+        result.ata = event.eventDateTime
+        result.ataOffset = event.eventDateTimeOffset ?? null
+      } else if ((classifierCode === 'PLN' || classifierCode === 'EST') && (atDestination || !context.destinationUnlocode)) {
+        result.eta = event.eventDateTime
+        result.etaOffset = event.eventDateTimeOffset ?? null
+      }
+    }
+  }
+
+  return result
+}