@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/lib/__tests__/vessel-api.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Tests for the vessel-api client — focused on fetchPois (the POI map feature).
+ *
+ * Covers query-param building, 404/error handling, and deduping by code
+ * (the live endpoint can return the same POI code more than once).
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { fetchPois, type PoiInfo } from '../vessel-api'
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+function makePoi(overrides: Partial<PoiInfo> & { code: string }): PoiInfo {
+  return {
+    code: overrides.code,
+    locode: overrides.locode ?? null as unknown as string,
+    type: overrides.type ?? 'WAYPOINT',
+    center: overrides.center ?? { lat: 0, lng: 0 },
+    radiusMeters: overrides.radiusMeters ?? 5000,
+    portName: overrides.portName ?? null,
+    terminalName: overrides.terminalName ?? null,
+    city: overrides.city ?? null,
+    country: overrides.country ?? null,
+    regionNamePl: overrides.regionNamePl ?? null,
+    regionNameEn: overrides.regionNameEn ?? null,
+  }
+}
+
+function mockFetchOnce(body: unknown, init?: { ok?: boolean; status?: number }) {
+  const ok = init?.ok ?? true
+  const status = init?.status ?? 200
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok,
+    status,
+    json: async () => body,
+  })
+  // @ts-expect-error - assigning a partial fetch mock for tests
+  global.fetch = fetchMock
+  return fetchMock
+}
+
+function lastUrl(fetchMock: ReturnType<typeof vi.fn>): string {
+  return String(fetchMock.mock.calls[0][0])
+}
+
+// ─── Tests ───────────────────────────────────────────────────
+
+describe('fetchPois', () => {
+  const originalFetch = global.fetch
+  const originalBaseUrl = process.env.NEXT_PUBLIC_VESSEL_API_URL
+
+  beforeEach(() => {
+    vi.restoreAllMocks()
+    process.env.NEXT_PUBLIC_VESSEL_API_URL = 'https://vessel.example.test'
+  })
+
+  afterEach(() => {
+    global.fetch = originalFetch
+    if (originalBaseUrl === undefined) delete process.env.NEXT_PUBLIC_VESSEL_API_URL
+    else process.env.NEXT_PUBLIC_VESSEL_API_URL = originalBaseUrl
+  })
+
+  it('dedupes POIs that share a code (live endpoint returns duplicates)', async () => {
+    const fetchMock = mockFetchOnce({
+      pois: [
+        makePoi({ code: 'N055E012-01920', regionNameEn: 'Baltic Sea' }),
+        makePoi({ code: 'N055E012-01920', regionNameEn: 'Baltic Sea (dup)' }),
+        makePoi({ code: 'PLGDY-T1', type: 'TERMINAL' }),
+      ],
+      count: 3,
+      limit: 1000,
+    })
+
+    const pois = await fetchPois()
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(pois).toHaveLength(2)
+    expect(pois.map((p) => p.code)).toEqual(['N055E012-01920', 'PLGDY-T1'])
+    // First occurrence wins
+    expect(pois[0].regionNameEn).toBe('Baltic Sea')
+  })
+
+  it('builds the bounding-box, type and limit query params', async () => {
+    const fetchMock = mockFetchOnce({ pois: [], count: 0, limit: 500 })
+
+    await fetchPois(
+      { north: 55.5, south: 53, east: 20, west: 12 },
+      { type: 'TERMINAL', limit: 500 }
+    )
+
+    const url = lastUrl(fetchMock)
+    expect(url).toContain('/poi?')
+    expect(url).toContain('north=55.5')
+    expect(url).toContain('south=53')
+    expect(url).toContain('east=20')
+    expect(url).toContain('west=12')
+    expect(url).toContain('type=TERMINAL')
+    expect(url).toContain('limit=500')
+  })
+
+  it('omits bounds/type/limit params when not provided', async () => {
+    const fetchMock = mockFetchOnce({ pois: [], count: 0, limit: 5000 })
+
+    await fetchPois()
+
+    const url = lastUrl(fetchMock)
+    expect(url).toMatch(/\/poi$/)
+    expect(url).not.toContain('?')
+  })
+
+  it('returns an empty array on 404', async () => {
+    mockFetchOnce({}, { ok: false, status: 404 })
+    await expect(fetchPois()).resolves.toEqual([])
+  })
+
+  it('throws with the API error message on a non-ok response', async () => {
+    mockFetchOnce({ error: 'Invalid bounding box values' }, { ok: false, status: 400 })
+    await expect(fetchPois()).rejects.toThrow('Invalid bounding box values')
+  })
+
+  it('returns an empty array when the response has no pois field', async () => {
+    mockFetchOnce({ count: 0, limit: 5000 })
+    await expect(fetchPois()).resolves.toEqual([])
+  })
+})

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

@@ -0,0 +1,108 @@
+import { findLatestVesselInfo } from '../vessel-extraction'
+
+describe('findLatestVesselInfo', () => {
+  it('should return null for empty array', () => {
+    expect(findLatestVesselInfo([])).toBeNull()
+  })
+
+  it('should return null when no events have vessel info', () => {
+    const events = [
+      { vesselName: null, vesselImo: null, voyageNumber: null },
+      { vesselName: undefined, vesselImo: undefined, voyageNumber: undefined },
+    ]
+    expect(findLatestVesselInfo(events)).toBeNull()
+  })
+
+  it('should return vessel info from the latest event with data', () => {
+    const events = [
+      { vesselName: 'VESSEL A', vesselImo: '1234567', voyageNumber: '001N' },
+      { vesselName: 'VESSEL B', vesselImo: '7654321', voyageNumber: '002N' },
+      { vesselName: null, vesselImo: null, voyageNumber: null }, // Gate operation
+    ]
+    expect(findLatestVesselInfo(events)).toEqual({
+      vesselName: 'VESSEL B',
+      vesselImo: '7654321',
+      voyageNumber: '002N',
+    })
+  })
+
+  it('should find vessel by vesselName only', () => {
+    const events = [
+      { vesselName: 'VESSEL A', vesselImo: null, voyageNumber: null },
+      { vesselName: null, vesselImo: null, voyageNumber: null },
+    ]
+    expect(findLatestVesselInfo(events)).toEqual({
+      vesselName: 'VESSEL A',
+      vesselImo: null,
+      voyageNumber: null,
+    })
+  })
+
+  it('should find vessel by vesselImo only', () => {
+    const events = [
+      { vesselName: null, vesselImo: '1234567', voyageNumber: null },
+      { vesselName: null, vesselImo: null, voyageNumber: null },
+    ]
+    expect(findLatestVesselInfo(events)).toEqual({
+      vesselName: null,
+      vesselImo: '1234567',
+      voyageNumber: null,
+    })
+  })
+
+  it('should find vessel by voyageNumber only', () => {
+    const events = [
+      { vesselName: null, vesselImo: null, voyageNumber: '001N' },
+      { vesselName: null, vesselImo: null, voyageNumber: null },
+    ]
+    expect(findLatestVesselInfo(events)).toEqual({
+      vesselName: null,
+      vesselImo: null,
+      voyageNumber: '001N',
+    })
+  })
+
+  it('should handle transshipment (multiple vessels)', () => {
+    const events = [
+      { vesselName: 'EXAMPLE VESSEL 07', vesselImo: '8000007', voyageNumber: '101N' },
+      { vesselName: 'EXAMPLE VESSEL 08', vesselImo: '8000008', voyageNumber: '102N' },
+      { vesselName: 'EXAMPLE VESSEL 06', vesselImo: '8000006', voyageNumber: '603N' },
+      { vesselName: null, vesselImo: null, voyageNumber: null }, // GTOT
+      { vesselName: null, vesselImo: null, voyageNumber: null }, // GTIN
+    ]
+    // Should return the last vessel (EXAMPLE VESSEL 06)
+    expect(findLatestVesselInfo(events)).toEqual({
+      vesselName: 'EXAMPLE VESSEL 06',
+      vesselImo: '8000006',
+      voyageNumber: '603N',
+    })
+  })
+
+  it('should handle partial vessel info', () => {
+    const events = [
+      { vesselName: 'VESSEL A', vesselImo: '1234567', voyageNumber: '001N' },
+      { vesselName: 'VESSEL B', vesselImo: null, voyageNumber: null }, // Only name
+      { vesselName: null, vesselImo: null, voyageNumber: null },
+    ]
+    // Should return VESSEL B with partial info
+    expect(findLatestVesselInfo(events)).toEqual({
+      vesselName: 'VESSEL B',
+      vesselImo: null,
+      voyageNumber: null,
+    })
+  })
+
+  it('should return first event vessel info when only one event has data', () => {
+    const events = [
+      { vesselName: 'FIRST VESSEL', vesselImo: '1111111', voyageNumber: '001N' },
+      { vesselName: null, vesselImo: null, voyageNumber: null },
+      { vesselName: null, vesselImo: null, voyageNumber: null },
+      { vesselName: null, vesselImo: null, voyageNumber: null },
+    ]
+    expect(findLatestVesselInfo(events)).toEqual({
+      vesselName: 'FIRST VESSEL',
+      vesselImo: '1111111',
+      voyageNumber: '001N',
+    })
+  })
+})

package/src/modules/shipment_tracking/lib/adapters/cma-cgm.ts

@@ -0,0 +1,84 @@
+import type { CarrierAdapter, CarrierFetchResult, CarrierAdapterTestResult } from '../carrier-adapter'
+import { extractDocumentReferences } from '../carrier-adapter'
+import type { TrackingReferenceType } from '../../data/entities'
+import { buildDcsaQueryParams } from '../dcsa-params'
+import { parseDcsaEvents } from '../dcsa-event-parser'
+import { withCarrierApiSpan } from '../logger'
+
+const EVENTS_URL = 'https://apis.cma-cgm.net/operation/trackandtrace/v1/events'
+
+type CmaCgmAuthConfig = {
+  api_key: string
+}
+
+function getAuth(authConfig: Record<string, unknown> | null | undefined): CmaCgmAuthConfig {
+  const apiKey = authConfig?.api_key as string | undefined
+  if (!apiKey) {
+    throw new Error('CMA CGM authConfig requires api_key')
+  }
+  return { api_key: apiKey }
+}
+
+export class CmaCgmAdapter implements CarrierAdapter {
+  readonly carrierCode = 'cma-cgm'
+  readonly supportedReferenceTypes: TrackingReferenceType[] = ['container', 'booking', 'bol']
+
+  async fetchEvents(input: {
+    referenceType: TrackingReferenceType
+    referenceValue: string
+    apiEndpoint?: string | null
+    authConfig?: Record<string, unknown> | null
+  }): Promise<CarrierFetchResult> {
+    return withCarrierApiSpan(
+      {
+        carrierCode: this.carrierCode,
+        operation: 'fetchEvents',
+        referenceType: input.referenceType,
+        referenceValue: input.referenceValue,
+      },
+      async (span) => {
+        const auth = getAuth(input.authConfig)
+        const params = buildDcsaQueryParams(input.referenceValue, input.referenceType)
+        const url = `${input.apiEndpoint || EVENTS_URL}?${params}`
+
+        const response = await fetch(url, {
+          headers: {
+            'Content-Type': 'application/json',
+            'keyId': auth.api_key,
+          },
+        })
+
+        span.setAttribute('http.status_code', response.status)
+
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => 'unknown')
+          throw new Error(`CMA CGM API error (${response.status}): ${errorText}`)
+        }
+
+        const data = await response.json()
+        const events = parseDcsaEvents(data, 'CMA CGM')
+        const { bookingNumber, bolNumber } = extractDocumentReferences(events)
+
+        span.setAttribute('events.count', events.length)
+        return { events, bookingNumber, bolNumber }
+      },
+    )
+  }
+
+  async testConnection(input: {
+    apiEndpoint?: string | null
+    authConfig?: Record<string, unknown> | null
+  }): Promise<CarrierAdapterTestResult> {
+    const start = Date.now()
+    try {
+      const auth = getAuth(input.authConfig)
+      if (!auth.api_key) {
+        throw new Error('Missing API key')
+      }
+      return { success: true, message: 'CMA CGM credentials validated', latencyMs: Date.now() - start }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      return { success: false, message: `CMA CGM connection failed: ${message}`, latencyMs: Date.now() - start }
+    }
+  }
+}

package/src/modules/shipment_tracking/lib/adapters/cosco-types.ts

@@ -0,0 +1,145 @@
+export type CoscoShipmentData = {
+  shipmentContent?: string
+  containerDetail?: CoscoContainer[] | CoscoContainer
+  queryCriteria?: {
+    bookingNumber?: string
+  }
+  billOfLadingNumber?: string[]
+}
+
+export type CoscoContainer = {
+  containerNumber?: {
+    containerNumber: string
+  }
+  event?: CoscoEvent[]
+  externalReference?: CoscoExternalReference[]
+  route?: {
+    shipmentLeg?: CoscoShipmentLeg[]
+  }
+}
+
+export type CoscoEvent = {
+  CSEvent?: {
+    CSEventCode: string
+  }
+  eventDescription?: string
+  carrEventCode?: string
+  eventDT?: CoscoDateTime
+  eventReceivedDT?: CoscoDateTime
+  location?: CoscoLocation
+  mode?: string
+  containerNumber?: string
+}
+
+export type CoscoExternalReference = {
+  CSReferenceType?: {
+    value: string
+  }
+  referenceNumber: string
+}
+
+export type CoscoDateTime = {
+  GMT?: {
+    text: string
+  }
+  locDT?: {
+    text?: string
+    _value?: {
+      time: string
+    }
+  }
+}
+
+export type CoscoDateTimeIndicator = {
+  indicator?: {
+    value: 'E' | 'A'
+  }
+  GMT?: {
+    text: string
+  }
+  locDT?: {
+    text: string
+  }
+}
+
+export type CoscoLocation = {
+  locationName?: string
+  cityDetails?: CoscoCityDetails
+  facility?: CoscoFacility
+  CSStandardCity?: {
+    CSCountryCode?: string
+  }
+}
+
+export type CoscoCityDetails = {
+  city?: string
+  country?: string
+  state?: string
+  portName?: string
+  locationCode?: {
+    UNLocationCode: string
+  }
+}
+
+export type CoscoFacility = {
+  facilityCode?: string
+  facilityName?: string
+}
+
+export type CoscoShipmentLeg = {
+  legSeq?: number
+  POL?: CoscoPort
+  POD?: CoscoPort
+  SVVD?: CoscoSVVD
+  arrivalDT?: CoscoDateTimeIndicator[]
+  departureDT?: CoscoDateTimeIndicator[]
+}
+
+export type CoscoPort = {
+  port?: {
+    portName?: string
+    city?: string
+    country?: string
+    state?: string
+    locationCode?: {
+      UNLocationCode: string
+    }
+  }
+  facility?: CoscoFacility
+}
+
+export type CoscoSVVD = {
+  loading?: CoscoVesselInfo
+  discharge?: CoscoVesselInfo
+}
+
+export type CoscoVesselInfo = {
+  vesselName: string
+  lloydsNumber?: string
+  callSign?: string
+  vessel?: string
+  voyage?: string
+  service?: string
+  direction?: string
+  callNumber?: string
+}
+
+export type ExtractedVesselData = {
+  vesselName: string
+  vesselIMONumber?: string
+  vesselCallSign?: string
+  vesselCode?: string
+  voyage?: string
+  service?: string
+  direction?: string
+  legType?: 'loading' | 'discharge'
+  legSequence?: number
+  pol?: string
+  pod?: string
+}
+
+export type DcsaEventMapping = {
+  eventType: string
+  eventCode: string
+  eventClassification: string
+}