@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/__tests__/shipsgo-client.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import {
+  registerOceanShipment,
+  getOceanShipment,
+  registerAirShipment,
+  ShipsGoCreditsExhaustedError,
+  ShipsGoAuthError,
+  ShipsGoRateLimitedError,
+  ShipsGoApiError,
+  normalizeAwbNumber,
+  type ShipsGoClientConfig,
+} from '../lib/shipsgo-client'
+
+/**
+ * TC-TRACK-414 — ShipsGo client register/fetch handling.
+ *
+ * Covers the credit/idempotency contract: 200 (created), 409 (already exists →
+ * free, same id), 402 (credits exhausted → typed error, never retried).
+ */
+
+const config: ShipsGoClientConfig = {
+  apiToken: 'test-token',
+  baseUrl: 'https://api.shipsgo.com/v2',
+}
+
+function mockFetch(status: number, body: unknown) {
+  return vi.fn().mockResolvedValue({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response)
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('registerOceanShipment', () => {
+  it('returns the id on 200 (created, credit spent)', async () => {
+    vi.stubGlobal('fetch', mockFetch(200, { message: 'SUCCESS', shipment: { id: 777 } }))
+    const result = await registerOceanShipment(config, { reference: 'job-1', bookingNumber: 'BK123' })
+    expect(result).toEqual({ id: '777', alreadyExisted: false })
+  })
+
+  it('treats 409 as success and returns the existing id (no charge)', async () => {
+    vi.stubGlobal('fetch', mockFetch(409, { message: 'ALREADY_EXISTS', shipment: { id: 555 } }))
+    const result = await registerOceanShipment(config, { reference: 'job-1', bookingNumber: 'BK123' })
+    expect(result).toEqual({ id: '555', alreadyExisted: true })
+  })
+
+  it('throws ShipsGoCreditsExhaustedError on 402', async () => {
+    vi.stubGlobal('fetch', mockFetch(402, { message: 'PAYMENT_REQUIRED' }))
+    await expect(
+      registerOceanShipment(config, { reference: 'job-1', bookingNumber: 'BK123' }),
+    ).rejects.toBeInstanceOf(ShipsGoCreditsExhaustedError)
+  })
+
+  it('sends booking_number and the job id as reference, omitting carrier when unset', async () => {
+    const fetchMock = mockFetch(200, { message: 'SUCCESS', shipment: { id: 1 } })
+    vi.stubGlobal('fetch', fetchMock)
+    await registerOceanShipment(config, { reference: 'job-42', bookingNumber: 'BK999' })
+
+    const [url, init] = fetchMock.mock.calls[0]
+    expect(url).toBe('https://api.shipsgo.com/v2/ocean/shipments')
+    expect(init.method).toBe('POST')
+    expect((init.headers as Record<string, string>)['X-Shipsgo-User-Token']).toBe('test-token')
+    const payload = JSON.parse(init.body as string)
+    expect(payload).toEqual({ reference: 'job-42', booking_number: 'BK999' })
+    expect(payload).not.toHaveProperty('carrier')
+  })
+
+  it('throws ShipsGoApiError on other non-2xx', async () => {
+    vi.stubGlobal('fetch', mockFetch(500, { message: 'ERROR' }))
+    await expect(
+      registerOceanShipment(config, { reference: 'job-1', containerNumber: 'MSCU1234567' }),
+    ).rejects.toBeInstanceOf(ShipsGoApiError)
+  })
+})
+
+describe('getOceanShipment', () => {
+  it('unwraps the shipment envelope', async () => {
+    vi.stubGlobal('fetch', mockFetch(200, { shipment: { id: 5, container_number: 'MSCU1' } }))
+    const shipment = await getOceanShipment(config, '5')
+    expect(shipment.id).toBe(5)
+    expect(shipment.container_number).toBe('MSCU1')
+  })
+})
+
+/**
+ * Account-level HTTP conditions (403 auth, 429 rate limit) must surface as their
+ * own typed errors on BOTH register and GET, so the poll loop backs the job off
+ * instead of burning its retry budget (like it already does for 402).
+ */
+function mockFetchWithHeaders(status: number, body: unknown, headers: Record<string, string> = {}) {
+  const lower: Record<string, string> = {}
+  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v
+  return vi.fn().mockResolvedValue({
+    ok: status >= 200 && status < 300,
+    status,
+    headers: { get: (name: string) => lower[name.toLowerCase()] ?? null },
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response)
+}
+
+describe('account-level errors (403 / 429)', () => {
+  it('throws ShipsGoAuthError on 403 (register)', async () => {
+    vi.stubGlobal('fetch', mockFetchWithHeaders(403, { message: 'FORBIDDEN' }))
+    await expect(
+      registerOceanShipment(config, { reference: 'job-1', bookingNumber: 'BK123' }),
+    ).rejects.toBeInstanceOf(ShipsGoAuthError)
+  })
+
+  it('throws ShipsGoAuthError on 403 (GET)', async () => {
+    vi.stubGlobal('fetch', mockFetchWithHeaders(403, { message: 'FORBIDDEN' }))
+    await expect(getOceanShipment(config, '5')).rejects.toBeInstanceOf(ShipsGoAuthError)
+  })
+
+  it('throws ShipsGoRateLimitedError on 429 with retryAfter from RateLimit-Reset', async () => {
+    const resetEpoch = Math.floor(Date.now() / 1000) + 42
+    vi.stubGlobal('fetch', mockFetchWithHeaders(429, { message: 'TOO_MANY' }, { 'RateLimit-Reset': String(resetEpoch) }))
+    const err = await registerOceanShipment(config, { reference: 'job-1', bookingNumber: 'BK123' }).catch((e) => e)
+    expect(err).toBeInstanceOf(ShipsGoRateLimitedError)
+    expect((err as ShipsGoRateLimitedError).retryAfterSeconds).toBeGreaterThan(0)
+    expect((err as ShipsGoRateLimitedError).retryAfterSeconds).toBeLessThanOrEqual(42)
+  })
+
+  it('429 without a reset header still throws (undefined retryAfter)', async () => {
+    vi.stubGlobal('fetch', mockFetchWithHeaders(429, { message: 'TOO_MANY' }))
+    const err = await getOceanShipment(config, '5').catch((e) => e)
+    expect(err).toBeInstanceOf(ShipsGoRateLimitedError)
+    expect((err as ShipsGoRateLimitedError).retryAfterSeconds).toBeUndefined()
+  })
+})
+
+describe('normalizeAwbNumber', () => {
+  it('hyphenates a bare 11-digit AWB', () => {
+    expect(normalizeAwbNumber('33388888888')).toBe('333-88888888')
+  })
+  it('normalizes spaced/hyphenated input to NNN-NNNNNNNN', () => {
+    expect(normalizeAwbNumber('333 8888 8888')).toBe('333-88888888')
+    expect(normalizeAwbNumber('333-88888888')).toBe('333-88888888')
+  })
+  it('leaves a non-11-digit value untouched (ShipsGo returns the authoritative error)', () => {
+    expect(normalizeAwbNumber('NOT-AN-AWB')).toBe('NOT-AN-AWB')
+  })
+  it('registerAirShipment sends the normalized awb_number', async () => {
+    const fetchMock = mockFetch(200, { message: 'SUCCESS', shipment: { id: 9 } })
+    vi.stubGlobal('fetch', fetchMock)
+    await registerAirShipment(config, { reference: 'job-air', awbNumber: '020 1234 5678' })
+    const payload = JSON.parse(fetchMock.mock.calls[0][1].body as string)
+    expect(payload.awb_number).toBe('020-12345678')
+  })
+})

package/src/modules/shipment_tracking/__tests__/shipsgo-mapper.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect } from 'vitest'
+import { mapOceanShipmentToEvents } from '../lib/shipsgo-mapper'
+import type { ShipsGoOceanShipment } from '../lib/shipsgo-client'
+
+/**
+ * TC-TRACK-411 — ShipsGo ocean movement mapping.
+ *
+ * Verifies mapOceanShipmentToEvents translates ShipsGo movements onto the
+ * internal DCSA-style event vocabulary the downstream pipeline understands.
+ */
+
+function shipment(overrides: Partial<ShipsGoOceanShipment> = {}): ShipsGoOceanShipment {
+  return {
+    id: 12345,
+    reference: 'job-abc',
+    booking_number: 'MEDUQY000000',
+    container_number: 'MSCU1234567',
+    carrier: { scac: 'MSCU', name: 'MSC', status: 'active' },
+    status: 'SAILING',
+    containers: [
+      {
+        number: 'MSCU1234567',
+        status: 'SAILING',
+        size: 40,
+        type: '45G1',
+        movements: [
+          {
+            event: 'GTIN',
+            status: 'ACT',
+            location: { code: 'PLGDN', name: 'Gdańsk', country: { code: 'PL', name: 'Poland' } },
+            vessel: null,
+            voyage: null,
+            timestamp: '2026-08-01T10:00:00Z',
+          },
+          {
+            event: 'LOAD',
+            status: 'ACT',
+            location: { code: 'PLGDN', name: 'Gdańsk', country: { code: 'PL', name: 'Poland' } },
+            vessel: { imo: 9839179, name: 'MSC GULSUN' },
+            voyage: 'FL512A',
+            timestamp: '2026-08-02T12:00:00Z',
+          },
+          {
+            event: 'DEPA',
+            status: 'ACT',
+            location: { code: 'PLGDN', name: 'Gdańsk', country: { code: 'PL', name: 'Poland' } },
+            vessel: { imo: 9839179, name: 'MSC GULSUN' },
+            voyage: 'FL512A',
+            timestamp: '2026-08-02T18:00:00Z',
+          },
+          {
+            event: 'ARRV',
+            status: 'EST',
+            location: { code: 'NLRTM', name: 'Rotterdam', country: { code: 'NL', name: 'Netherlands' } },
+            vessel: { imo: 9839179, name: 'MSC GULSUN' },
+            voyage: 'FL512A',
+            timestamp: '2026-08-20T06:00:00Z',
+          },
+        ],
+      },
+    ],
+    ...overrides,
+  }
+}
+
+describe('mapOceanShipmentToEvents', () => {
+  it('maps ocean movement codes onto the DCSA vocabulary with equipment reference', () => {
+    const result = mapOceanShipmentToEvents(shipment())
+
+    expect(result.events).toHaveLength(4)
+    const byCode = Object.fromEntries(result.events.map((e) => [e.eventCode, e]))
+
+    expect(byCode.GTIN.eventType).toBe('EQUIPMENT')
+    expect(byCode.LOAD.eventType).toBe('EQUIPMENT')
+    expect(byCode.DEPA.eventType).toBe('TRANSPORT')
+    // ShipsGo ARRV → DCSA ARRI (transport arrival)
+    expect(byCode.ARRI.eventType).toBe('TRANSPORT')
+
+    for (const e of result.events) {
+      expect(e.source).toBe('shipsgo')
+      expect(e.equipmentReference).toBe('MSCU1234567')
+    }
+  })
+
+  it('maps ShipsGo status EST/ACT onto the event classifier', () => {
+    const result = mapOceanShipmentToEvents(shipment())
+    const arri = result.events.find((e) => e.eventCode === 'ARRI')!
+    const gtin = result.events.find((e) => e.eventCode === 'GTIN')!
+    expect(arri.eventClassifierCode).toBe('EST')
+    expect(gtin.eventClassifierCode).toBe('ACT')
+  })
+
+  it('extracts vessel + location details from movements', () => {
+    const result = mapOceanShipmentToEvents(shipment())
+    const depa = result.events.find((e) => e.eventCode === 'DEPA')!
+    expect(depa.vesselName).toBe('MSC GULSUN')
+    expect(depa.vesselImo).toBe('9839179')
+    expect(depa.voyageNumber).toBe('FL512A')
+    expect(depa.modeOfTransport).toBe('VESSEL')
+    expect(depa.locationUnlocode).toBe('PLGDN')
+    expect(depa.locationCountry).toBe('PL')
+    // Result carries the latest vessel + top-level references
+    expect(result.vesselName).toBe('MSC GULSUN')
+    expect(result.vesselImo).toBe('9839179')
+    expect(result.containerNumber).toBe('MSCU1234567')
+    expect(result.bookingNumber).toBe('MEDUQY000000')
+  })
+
+  it('persists the local UTC offset from the ShipsGo timestamp (eventDateTimeOffset)', () => {
+    const s = shipment({
+      containers: [
+        {
+          number: 'MSCU1234567',
+          status: 'SAILING',
+          movements: [
+            { event: 'LOAD', status: 'ACT', location: { code: 'CNYTN', name: 'Yantian' }, vessel: null, voyage: null, timestamp: '2026-07-29T12:00:00+08:00' },
+            { event: 'DISC', status: 'ACT', location: { code: 'PLGDN', name: 'Gdańsk' }, vessel: null, voyage: null, timestamp: '2026-09-07T10:00:00Z' },
+          ],
+        },
+      ],
+    })
+    const byCode = Object.fromEntries(mapOceanShipmentToEvents(s).events.map((e) => [e.eventCode, e]))
+    expect(byCode['LOAD'].eventDateTimeOffset).toBe('+08:00')
+    expect(byCode['DISC'].eventDateTimeOffset).toBeNull() // Z / UTC
+  })
+
+  it('maps container size + type onto isoEquipmentCode (readable equipment code)', () => {
+    const s = shipment({
+      containers: [
+        {
+          number: 'CSGU6009557',
+          status: 'DISCHARGED',
+          size: 40,
+          type: 'HC',
+          movements: [
+            { event: 'LOAD', status: 'ACT', location: { code: 'CNYTN', name: 'Yantian' }, vessel: null, voyage: null, timestamp: '2026-07-29T04:00:00Z' },
+          ],
+        },
+      ],
+    })
+    const result = mapOceanShipmentToEvents(s)
+    expect(result.events[0].isoEquipmentCode).toBe('40HC')
+  })
+
+  it('captures the ShipsGo route summary into extra (POL/POD, transit, CO2)', () => {
+    const s = shipment({
+      route: {
+        port_of_loading: { location: { code: 'CNYTN', name: 'YANTIAN (SHENZHEN)' }, date_of_loading: '2026-07-29T12:00:00+08:00' },
+        port_of_discharge: { location: { code: 'PLGDN', name: 'GDANSK' }, date_of_discharge: '2026-09-07T12:00:00+02:00', date_of_discharge_predicted: null },
+        transit_time: 40,
+        transit_percentage: 100,
+        co2_emission: 63.08,
+        ts_count: 0,
+      },
+    })
+    const extra = mapOceanShipmentToEvents(s).extra as any
+    expect(extra.shipsgoRoute.portOfLoading).toEqual({ unlocode: 'CNYTN', name: 'YANTIAN (SHENZHEN)' })
+    expect(extra.shipsgoRoute.portOfDischarge).toEqual({ unlocode: 'PLGDN', name: 'GDANSK' })
+    expect(extra.shipsgoRoute.transitTimeDays).toBe(40)
+    expect(extra.shipsgoRoute.co2Emission).toBe(63.08)
+    expect(extra.shipsgoRoute.transshipmentCount).toBe(0)
+  })
+
+  it('leaves extra null when the shipment has no route', () => {
+    expect(mapOceanShipmentToEvents(shipment()).extra).toBeNull()
+  })
+
+  it('produces deterministic, unique source event ids for dedup', () => {
+    const a = mapOceanShipmentToEvents(shipment())
+    const b = mapOceanShipmentToEvents(shipment())
+    const idsA = a.events.map((e) => e.sourceEventId)
+    const idsB = b.events.map((e) => e.sourceEventId)
+    expect(idsA).toEqual(idsB) // deterministic across polls
+    expect(new Set(idsA).size).toBe(idsA.length) // unique within a poll
+  })
+
+  it('skips unknown event codes and invalid timestamps', () => {
+    const s = shipment({
+      containers: [
+        {
+          number: 'MSCU7654321',
+          movements: [
+            { event: 'XXXX', status: 'ACT', timestamp: '2026-08-01T10:00:00Z' },
+            { event: 'GTIN', status: 'ACT', timestamp: 'not-a-date' },
+            { event: 'DISC', status: 'ACT', timestamp: '2026-08-21T10:00:00Z' },
+          ],
+        },
+      ],
+    })
+    const result = mapOceanShipmentToEvents(s)
+    expect(result.events).toHaveLength(1)
+    expect(result.events[0].eventCode).toBe('DISC')
+    expect(result.events[0].equipmentReference).toBe('MSCU7654321')
+  })
+
+  it('handles a shipment with no containers', () => {
+    const result = mapOceanShipmentToEvents(shipment({ containers: [], container_number: null }))
+    expect(result.events).toEqual([])
+    expect(result.containerNumber).toBeNull()
+  })
+})