@freighttech/shipment-tracking 0.6.0

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

@@ -0,0 +1,331 @@
+import { extractShipmentTimes } from '../time-extraction'
+import { parseDcsaEvents } from '../dcsa-event-parser'
+import { fixtures, sortEventsByTime } from '../../__tests__/fixtures'
+
+describe('time-extraction', () => {
+  describe('extractShipmentTimes', () => {
+    describe('basic extraction', () => {
+      it('should extract ETD from planned DEPA at origin', () => {
+        const events = [
+          {
+            eventCode: 'DEPA',
+            eventClassifierCode: 'PLN' as const,
+            eventDateTime: new Date('2025-01-10T10:00:00Z'),
+            eventDateTimeOffset: '+08:00',
+            locationUnlocode: 'CNYTN',
+          },
+        ]
+        const result = extractShipmentTimes(events, { originUnlocode: 'CNYTN' })
+
+        expect(result.etd).toEqual(new Date('2025-01-10T10:00:00Z'))
+        expect(result.etdOffset).toBe('+08:00')
+      })
+
+      it('should extract ETD from estimated DEPA at origin', () => {
+        const events = [
+          {
+            eventCode: 'DEPA',
+            eventClassifierCode: 'EST' as const,
+            eventDateTime: new Date('2025-01-10T10:00:00Z'),
+            eventDateTimeOffset: '+08:00',
+            locationUnlocode: 'CNYTN',
+          },
+        ]
+        const result = extractShipmentTimes(events, { originUnlocode: 'CNYTN' })
+
+        expect(result.etd).toEqual(new Date('2025-01-10T10:00:00Z'))
+      })
+
+      it('should extract ATD from actual DEPA at origin', () => {
+        const events = [
+          {
+            eventCode: 'DEPA',
+            eventClassifierCode: 'ACT' as const,
+            eventDateTime: new Date('2025-01-10T10:00:00Z'),
+            eventDateTimeOffset: '+08:00',
+            locationUnlocode: 'CNYTN',
+          },
+        ]
+        const result = extractShipmentTimes(events, { originUnlocode: 'CNYTN' })
+
+        expect(result.atd).toEqual(new Date('2025-01-10T10:00:00Z'))
+        expect(result.atdOffset).toBe('+08:00')
+      })
+
+      it('should extract ETA from planned ARRI at destination', () => {
+        const events = [
+          {
+            eventCode: 'ARRI',
+            eventClassifierCode: 'PLN' as const,
+            eventDateTime: new Date('2025-02-15T08:00:00Z'),
+            eventDateTimeOffset: '+01:00',
+            locationUnlocode: 'PLGDN',
+          },
+        ]
+        const result = extractShipmentTimes(events, { destinationUnlocode: 'PLGDN' })
+
+        expect(result.eta).toEqual(new Date('2025-02-15T08:00:00Z'))
+        expect(result.etaOffset).toBe('+01:00')
+      })
+
+      it('should extract ETA from estimated ARRI at destination', () => {
+        const events = [
+          {
+            eventCode: 'ARRI',
+            eventClassifierCode: 'EST' as const,
+            eventDateTime: new Date('2025-02-15T08:00:00Z'),
+            locationUnlocode: 'PLGDN',
+          },
+        ]
+        const result = extractShipmentTimes(events, { destinationUnlocode: 'PLGDN' })
+
+        expect(result.eta).toEqual(new Date('2025-02-15T08:00:00Z'))
+      })
+
+      it('should extract ATA from actual ARRI at destination', () => {
+        const events = [
+          {
+            eventCode: 'ARRI',
+            eventClassifierCode: 'ACT' as const,
+            eventDateTime: new Date('2025-02-15T08:00:00Z'),
+            eventDateTimeOffset: '+01:00',
+            locationUnlocode: 'PLGDN',
+          },
+        ]
+        const result = extractShipmentTimes(events, { destinationUnlocode: 'PLGDN' })
+
+        expect(result.ata).toEqual(new Date('2025-02-15T08:00:00Z'))
+        expect(result.ataOffset).toBe('+01:00')
+      })
+    })
+
+    describe('latest event wins', () => {
+      it('should use later ETD when multiple planned DEPA events exist', () => {
+        const events = [
+          {
+            eventCode: 'DEPA',
+            eventClassifierCode: 'PLN' as const,
+            eventDateTime: new Date('2025-01-10T10:00:00Z'),
+            locationUnlocode: 'CNYTN',
+          },
+          {
+            eventCode: 'DEPA',
+            eventClassifierCode: 'PLN' as const,
+            eventDateTime: new Date('2025-01-12T10:00:00Z'), // Later
+            locationUnlocode: 'CNYTN',
+          },
+        ]
+        const result = extractShipmentTimes(events, { originUnlocode: 'CNYTN' })
+
+        expect(result.etd).toEqual(new Date('2025-01-12T10:00:00Z'))
+      })
+
+      it('should use later ETA when multiple estimated ARRI events exist', () => {
+        const events = [
+          {
+            eventCode: 'ARRI',
+            eventClassifierCode: 'EST' as const,
+            eventDateTime: new Date('2025-02-15T08:00:00Z'),
+            locationUnlocode: 'PLGDN',
+          },
+          {
+            eventCode: 'ARRI',
+            eventClassifierCode: 'EST' as const,
+            eventDateTime: new Date('2025-02-18T08:00:00Z'), // Updated ETA
+            locationUnlocode: 'PLGDN',
+          },
+        ]
+        const result = extractShipmentTimes(events, { destinationUnlocode: 'PLGDN' })
+
+        expect(result.eta).toEqual(new Date('2025-02-18T08:00:00Z'))
+      })
+    })
+
+    describe('without location context', () => {
+      it('should extract ATD from DEPA ACT when origin unknown', () => {
+        const events = [
+          {
+            eventCode: 'DEPA',
+            eventClassifierCode: 'ACT' as const,
+            eventDateTime: new Date('2025-01-10T10:00:00Z'),
+            locationUnlocode: 'CNYTN',
+          },
+        ]
+        // No origin specified
+        const result = extractShipmentTimes(events, {})
+
+        expect(result.atd).toEqual(new Date('2025-01-10T10:00:00Z'))
+      })
+
+      it('should extract ATA from ARRI ACT when destination unknown', () => {
+        const events = [
+          {
+            eventCode: 'ARRI',
+            eventClassifierCode: 'ACT' as const,
+            eventDateTime: new Date('2025-02-15T08:00:00Z'),
+            locationUnlocode: 'PLGDN',
+          },
+        ]
+        // No destination specified
+        const result = extractShipmentTimes(events, {})
+
+        expect(result.ata).toEqual(new Date('2025-02-15T08:00:00Z'))
+      })
+    })
+
+    describe('ignores non-matching locations', () => {
+      it('should not extract ATD from DEPA at non-origin port', () => {
+        const events = [
+          {
+            eventCode: 'DEPA',
+            eventClassifierCode: 'ACT' as const,
+            eventDateTime: new Date('2025-01-10T10:00:00Z'),
+            locationUnlocode: 'CNNGB', // Transship port, not origin
+          },
+        ]
+        const result = extractShipmentTimes(events, {
+          originUnlocode: 'CNYTN',
+          destinationUnlocode: 'PLGDN',
+        })
+
+        // Should not extract as it's not at origin
+        expect(result.atd).toBeUndefined()
+      })
+
+      it('should not extract ATA from ARRI at non-destination port', () => {
+        const events = [
+          {
+            eventCode: 'ARRI',
+            eventClassifierCode: 'ACT' as const,
+            eventDateTime: new Date('2025-01-15T08:00:00Z'),
+            locationUnlocode: 'CNNGB', // Transship port, not destination
+          },
+        ]
+        const result = extractShipmentTimes(events, {
+          originUnlocode: 'CNYTN',
+          destinationUnlocode: 'PLGDN',
+        })
+
+        // Should not extract as it's not at destination
+        expect(result.ata).toBeUndefined()
+      })
+    })
+
+    describe('with real MSC direct voyage fixture', () => {
+      it('should extract ATD and ETA from events', () => {
+        const parsed = parseDcsaEvents(fixtures.direct.events, 'MSC')
+        const events = parsed.map((e) => ({
+          eventCode: e.eventCode,
+          eventClassifierCode: e.eventClassifierCode,
+          eventDateTime: e.eventDateTime,
+          eventDateTimeOffset: e.eventDateTimeOffset,
+          locationUnlocode: e.locationUnlocode,
+        }))
+
+        const result = extractShipmentTimes(events, {
+          originUnlocode: fixtures.direct.origin,
+          destinationUnlocode: fixtures.direct.destination,
+        })
+
+        // Should have ATD from DEPA ACT at origin
+        expect(result.atd).toBeDefined()
+        expect(result.atd!.toISOString()).toBe('2026-01-06T02:18:00.000Z') // DEPA at CNYTN
+
+        // Should have ETA from ARRI EST at destination
+        expect(result.eta).toBeDefined()
+        expect(result.eta!.toISOString()).toBe('2026-02-20T05:00:00.000Z') // EST ARRI at PLGDN
+      })
+    })
+
+    describe('with real MSC transshipment fixture', () => {
+      it('should extract times correctly with transshipment', () => {
+        const parsed = parseDcsaEvents(fixtures.transshipment.events, 'MSC')
+        const events = parsed.map((e) => ({
+          eventCode: e.eventCode,
+          eventClassifierCode: e.eventClassifierCode,
+          eventDateTime: e.eventDateTime,
+          eventDateTimeOffset: e.eventDateTimeOffset,
+          locationUnlocode: e.locationUnlocode,
+        }))
+
+        const result = extractShipmentTimes(events, {
+          originUnlocode: fixtures.transshipment.origin,
+          destinationUnlocode: fixtures.transshipment.destination,
+        })
+
+        // ATD should be from first DEPA at origin (CNTAO)
+        expect(result.atd).toBeDefined()
+
+        // ETA should be from EST ARRI at destination (PLGDN)
+        expect(result.eta).toBeDefined()
+
+        // Should NOT have ATA yet (shipment not arrived)
+        expect(result.ata).toBeUndefined()
+      })
+
+      it('should extract ATD from origin not transship port', () => {
+        const parsed = parseDcsaEvents(fixtures.transshipment.events, 'MSC')
+        const events = parsed.map((e) => ({
+          eventCode: e.eventCode,
+          eventClassifierCode: e.eventClassifierCode,
+          eventDateTime: e.eventDateTime,
+          eventDateTimeOffset: e.eventDateTimeOffset,
+          locationUnlocode: e.locationUnlocode,
+        }))
+
+        const result = extractShipmentTimes(events, {
+          originUnlocode: fixtures.transshipment.origin,
+          destinationUnlocode: fixtures.transshipment.destination,
+        })
+
+        // ATD location should be origin
+        const depaAtOrigin = parsed.find(
+          (e) =>
+            e.eventCode === 'DEPA' &&
+            e.eventClassifierCode === 'ACT' &&
+            e.locationUnlocode === fixtures.transshipment.origin,
+        )
+
+        expect(depaAtOrigin).toBeDefined()
+        expect(result.atd).toEqual(depaAtOrigin!.eventDateTime)
+      })
+    })
+
+    describe('edge cases', () => {
+      it('should return empty object when no events', () => {
+        const result = extractShipmentTimes([], {})
+        expect(result).toEqual({})
+      })
+
+      it('should handle events with null offset', () => {
+        const events = [
+          {
+            eventCode: 'DEPA',
+            eventClassifierCode: 'ACT' as const,
+            eventDateTime: new Date('2025-01-10T10:00:00Z'),
+            eventDateTimeOffset: null,
+            locationUnlocode: 'CNYTN',
+          },
+        ]
+        const result = extractShipmentTimes(events, {})
+
+        expect(result.atd).toBeDefined()
+        expect(result.atdOffset).toBeNull()
+      })
+
+      it('should handle case-insensitive location matching', () => {
+        const events = [
+          {
+            eventCode: 'ARRI',
+            eventClassifierCode: 'ACT' as const,
+            eventDateTime: new Date('2025-02-15T08:00:00Z'),
+            locationUnlocode: 'plgdn', // lowercase
+          },
+        ]
+        const result = extractShipmentTimes(events, { destinationUnlocode: 'PLGDN' })
+
+        expect(result.ata).toBeDefined()
+      })
+    })
+  })
+})

package/src/modules/shipment_tracking/lib/__tests__/timestamp-utils.test.ts

@@ -0,0 +1,260 @@
+import {
+  getLatestTimestamp,
+  getPrimaryTimestampValue,
+  getPrimaryTimestampOffset,
+  createTimestampEntry,
+  addTimestampEntry,
+  mergeExtractedTimestamps,
+  hasTimestamps,
+  getTimestampsBySource,
+  getTimestampHistory,
+  type ShipmentTimestampEntry,
+} from '../timestamp-utils'
+
+describe('timestamp-utils', () => {
+  describe('createTimestampEntry', () => {
+    it('should create entry from Date', () => {
+      const date = new Date('2026-02-24T15:30:00Z')
+      const entry = createTimestampEntry(date, '+08:00', 'carrier_api', 'evt-123')
+
+      expect(entry.value).toBe('2026-02-24T15:30:00.000Z')
+      expect(entry.offset).toBe('+08:00')
+      expect(entry.source).toBe('carrier_api')
+      expect(entry.sourceEventId).toBe('evt-123')
+      expect(entry.updatedAt).toBeDefined()
+    })
+
+    it('should create entry from ISO string', () => {
+      const entry = createTimestampEntry('2026-02-24T15:30:00Z', null, 'manual')
+
+      expect(entry.value).toBe('2026-02-24T15:30:00.000Z')
+      expect(entry.offset).toBeNull()
+      expect(entry.source).toBe('manual')
+      expect(entry.sourceEventId).toBeNull()
+    })
+  })
+
+  describe('getLatestTimestamp', () => {
+    it('should return null for empty array', () => {
+      expect(getLatestTimestamp([])).toBeNull()
+      expect(getLatestTimestamp(null)).toBeNull()
+      expect(getLatestTimestamp(undefined)).toBeNull()
+    })
+
+    it('should return single entry', () => {
+      const entries: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T15:30:00Z', offset: '+08:00', source: 'carrier_api', updatedAt: '2026-02-18T10:00:00Z' },
+      ]
+
+      const result = getLatestTimestamp(entries)
+      expect(result).not.toBeNull()
+      expect(result!.value.toISOString()).toBe('2026-02-24T15:30:00.000Z')
+      expect(result!.offset).toBe('+08:00')
+      expect(result!.source).toBe('carrier_api')
+    })
+
+    it('should return entry with latest updatedAt', () => {
+      const entries: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T10:00:00Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-17T10:00:00Z' },
+        { value: '2026-02-24T15:30:00Z', offset: '+08:00', source: 'manual', updatedAt: '2026-02-18T12:00:00Z' },
+        { value: '2026-02-24T12:00:00Z', offset: null, source: 'ais', updatedAt: '2026-02-18T08:00:00Z' },
+      ]
+
+      const result = getLatestTimestamp(entries)
+      expect(result!.value.toISOString()).toBe('2026-02-24T15:30:00.000Z')
+      expect(result!.source).toBe('manual')
+    })
+  })
+
+  describe('getPrimaryTimestampValue', () => {
+    it('should return Date from latest entry', () => {
+      const entries: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T15:30:00Z', offset: '+08:00', source: 'carrier_api', updatedAt: '2026-02-18T10:00:00Z' },
+      ]
+
+      const result = getPrimaryTimestampValue(entries)
+      expect(result).toBeInstanceOf(Date)
+      expect(result!.toISOString()).toBe('2026-02-24T15:30:00.000Z')
+    })
+
+    it('should return null for empty', () => {
+      expect(getPrimaryTimestampValue(null)).toBeNull()
+    })
+  })
+
+  describe('getPrimaryTimestampOffset', () => {
+    it('should return offset from latest entry', () => {
+      const entries: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T15:30:00Z', offset: '+08:00', source: 'carrier_api', updatedAt: '2026-02-18T10:00:00Z' },
+      ]
+
+      expect(getPrimaryTimestampOffset(entries)).toBe('+08:00')
+    })
+
+    it('should return null for null offset', () => {
+      const entries: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T15:30:00Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-18T10:00:00Z' },
+      ]
+
+      expect(getPrimaryTimestampOffset(entries)).toBeNull()
+    })
+  })
+
+  describe('addTimestampEntry', () => {
+    it('should add entry to empty array', () => {
+      const entry = createTimestampEntry('2026-02-24T15:30:00Z', null, 'carrier_api')
+      const result = addTimestampEntry(null, entry)
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toBe(entry)
+    })
+
+    it('should add entry to existing array', () => {
+      const existing: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T10:00:00Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-17T10:00:00Z' },
+      ]
+      const entry = createTimestampEntry('2026-02-24T15:30:00Z', null, 'manual')
+      const result = addTimestampEntry(existing, entry)
+
+      expect(result).toHaveLength(2)
+    })
+
+    it('should dedupe by value+source', () => {
+      const existing: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T15:30:00.000Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-17T10:00:00Z' },
+      ]
+      const entry = createTimestampEntry('2026-02-24T15:30:00Z', null, 'carrier_api')
+      const result = addTimestampEntry(existing, entry)
+
+      expect(result).toHaveLength(1) // Not added - duplicate
+    })
+
+    it('should allow same value from different source', () => {
+      const existing: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T15:30:00.000Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-17T10:00:00Z' },
+      ]
+      const entry = createTimestampEntry('2026-02-24T15:30:00Z', null, 'manual')
+      const result = addTimestampEntry(existing, entry)
+
+      expect(result).toHaveLength(2) // Added - different source
+    })
+
+    it('should allow different value from same source (SCD pattern)', () => {
+      const existing: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T10:00:00.000Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-17T10:00:00Z' },
+      ]
+      const entry = createTimestampEntry('2026-02-24T15:30:00Z', null, 'carrier_api')
+      const result = addTimestampEntry(existing, entry)
+
+      expect(result).toHaveLength(2) // Added - different value
+    })
+  })
+
+  describe('mergeExtractedTimestamps', () => {
+    it('should merge extracted times into empty arrays', () => {
+      const result = mergeExtractedTimestamps(
+        {},
+        {
+          etd: new Date('2026-02-20T10:00:00Z'),
+          etdOffset: '+08:00',
+          eta: new Date('2026-02-25T15:00:00Z'),
+          etaOffset: '+01:00',
+        },
+        'carrier_api',
+        'evt-123',
+      )
+
+      expect(result.changed).toBe(true)
+      expect(result.etdTimestamps).toHaveLength(1)
+      expect(result.etaTimestamps).toHaveLength(1)
+      expect(result.atdTimestamps).toBeNull()
+      expect(result.ataTimestamps).toBeNull()
+    })
+
+    it('should merge extracted times into existing arrays', () => {
+      const existing = {
+        etdTimestamps: [
+          { value: '2026-02-20T08:00:00.000Z', offset: null, source: 'carrier_api' as const, updatedAt: '2026-02-17T10:00:00Z' },
+        ],
+      }
+
+      const result = mergeExtractedTimestamps(
+        existing,
+        {
+          etd: new Date('2026-02-20T12:00:00Z'),
+          etdOffset: '+08:00',
+        },
+        'carrier_api',
+        'evt-456',
+      )
+
+      expect(result.changed).toBe(true)
+      expect(result.etdTimestamps).toHaveLength(2)
+    })
+
+    it('should not add duplicate times', () => {
+      const existing = {
+        etdTimestamps: [
+          { value: '2026-02-20T10:00:00.000Z', offset: '+08:00', source: 'carrier_api' as const, updatedAt: '2026-02-17T10:00:00Z' },
+        ],
+      }
+
+      const result = mergeExtractedTimestamps(
+        existing,
+        {
+          etd: new Date('2026-02-20T10:00:00Z'),
+          etdOffset: '+08:00',
+        },
+        'carrier_api',
+      )
+
+      expect(result.changed).toBe(false)
+      expect(result.etdTimestamps).toHaveLength(1)
+    })
+  })
+
+  describe('hasTimestamps', () => {
+    it('should return false for empty/null', () => {
+      expect(hasTimestamps(null)).toBe(false)
+      expect(hasTimestamps(undefined)).toBe(false)
+      expect(hasTimestamps([])).toBe(false)
+    })
+
+    it('should return true for non-empty array', () => {
+      const entries: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T15:30:00Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-18T10:00:00Z' },
+      ]
+      expect(hasTimestamps(entries)).toBe(true)
+    })
+  })
+
+  describe('getTimestampsBySource', () => {
+    it('should filter by source', () => {
+      const entries: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T10:00:00Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-17T10:00:00Z' },
+        { value: '2026-02-24T12:00:00Z', offset: null, source: 'manual', updatedAt: '2026-02-17T12:00:00Z' },
+        { value: '2026-02-24T14:00:00Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-17T14:00:00Z' },
+      ]
+
+      const result = getTimestampsBySource(entries, 'carrier_api')
+      expect(result).toHaveLength(2)
+      expect(result.every(e => e.source === 'carrier_api')).toBe(true)
+    })
+  })
+
+  describe('getTimestampHistory', () => {
+    it('should sort by updatedAt ascending', () => {
+      const entries: ShipmentTimestampEntry[] = [
+        { value: '2026-02-24T14:00:00Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-18T14:00:00Z' },
+        { value: '2026-02-24T10:00:00Z', offset: null, source: 'carrier_api', updatedAt: '2026-02-18T10:00:00Z' },
+        { value: '2026-02-24T12:00:00Z', offset: null, source: 'manual', updatedAt: '2026-02-18T12:00:00Z' },
+      ]
+
+      const result = getTimestampHistory(entries)
+      expect(result).toHaveLength(3)
+      expect(result[0].updatedAt).toBe('2026-02-18T10:00:00Z')
+      expect(result[1].updatedAt).toBe('2026-02-18T12:00:00Z')
+      expect(result[2].updatedAt).toBe('2026-02-18T14:00:00Z')
+    })
+  })
+})