@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/services/__tests__/availabilityEmit.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { checkRateLimit, findOneWithDecryption } = vi.hoisted(() => ({
+  checkRateLimit: vi.fn(),
+  findOneWithDecryption: vi.fn(),
+}))
+vi.mock('../../lib/rate-limiter', () => ({ checkRateLimit }))
+vi.mock('@open-mercato/shared/lib/encryption/find', () => ({ findOneWithDecryption }))
+
+import { TerminalTrackingService } from '../terminalTrackingService'
+
+const CONFIG = {
+  terminalCode: 'bct',
+  adapterType: 'n4',
+  displayName: 'Baltic Hub',
+  baseUrl: 'https://api2.baltichub.com/V1/',
+  endpoints: { unit: '/unit' }, // no vessel endpoint → skip enrichment
+  authType: 'oauth2_password',
+  tokenUrl: null,
+  scope: null,
+  clientId: null,
+  authConfig: null,
+  rateLimitRequests: 200,
+  rateLimitWindowSeconds: 60,
+  unlocode: 'PLGDN',
+  smdgCodes: ['GDNBCT'],
+  bicCodes: [],
+  vesselCacheTtlSeconds: null,
+}
+
+const DT = new Date('2026-06-03T01:58:00Z')
+
+function unitEvent(overrides: Record<string, unknown>) {
+  return {
+    source: 'terminal',
+    sourceEventId: 'bct:C1:DISC',
+    eventType: 'EQUIPMENT',
+    eventCode: 'DISC', // yard, not DEPA → job stays active
+    eventClassifierCode: 'ACT',
+    eventDateTime: DT,
+    containerNumber: 'C1',
+    ufvGkey: 'C1',
+    transitState: 'S40_YARD',
+    visitState: null,
+    impediments: null,
+    visitRefIn: null,
+    visitRefOut: null,
+    rawData: {},
+    ...overrides,
+  }
+}
+
+/**
+ * Harness: one job for container C1. `events` is what /unit returns each poll;
+ * `existingEvents` are the persisted TerminalEvents already on the job (to model
+ * a prior poll's state for the holds-cleared transition).
+ */
+function makeHarness(events: any[], existingEvents: any[] = []) {
+  const job = {
+    id: 'job-1',
+    organizationId: 'org-1',
+    tenantId: 'ten-1',
+    terminalCode: 'bct',
+    containerNumber: 'C1',
+    schedule: null,
+    status: 'active',
+    emptyReadyAt: null,
+    holdsClearedAt: null,
+  }
+
+  // Adapter without fetchVesselVisit → enrichment is skipped entirely.
+  const adapter = {
+    adapterType: 'n4',
+    defaultEndpoints: { unit: '/unit' },
+    fetchEvents: vi.fn(),
+    fetchEventsBatch: vi.fn(async () => ({ events })),
+    testConnection: vi.fn(),
+  }
+
+  const em = {
+    fork() {
+      return this
+    },
+    async find(_entity: any, where: any) {
+      if (where && 'status' in where) return [job] // stable job instance across polls
+      if (where && 'sourceEventId' in where) return existingEvents // persistEvents lookup
+      return []
+    },
+    create(_entity: any, data: any) {
+      return { ...data }
+    },
+    async flush() {},
+  }
+
+  const eventBus = { emit: vi.fn(async () => {}) }
+  const service = new TerminalTrackingService({
+    em: () => em as never,
+    eventBus: eventBus as never,
+    terminalRegistry: { get: () => adapter } as never,
+    cacheService: { get: async () => null, set: async () => {} } as never,
+  })
+  return { service, eventBus, job }
+}
+
+function emitsOf(eventBus: any, id: string) {
+  return eventBus.emit.mock.calls.filter((c: any[]) => c[0] === id)
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  checkRateLimit.mockResolvedValue({ allowed: true })
+  findOneWithDecryption.mockResolvedValue({ ...CONFIG })
+})
+
+describe('availability emission', () => {
+  it('emits empty_ready for an empty export in the yard with no blocking holds', async () => {
+    const { service, eventBus } = makeHarness([
+      unitEvent({ rawData: { Category: 'Export', 'Frght Kind': 'MTY' } }),
+    ])
+
+    await service.pollAllActiveJobs('ten-1')
+
+    const emits = emitsOf(eventBus, 'terminal_tracking.equipment.empty_ready')
+    expect(emits).toHaveLength(1)
+    expect(emits[0][1]).toMatchObject({ containerNumber: 'C1', emptyReady: true })
+    // Not an import → no holds_cleared.
+    expect(emitsOf(eventBus, 'terminal_tracking.equipment.holds_cleared')).toHaveLength(0)
+  })
+
+  it('is one-shot: does not re-emit empty_ready on a second poll', async () => {
+    const { service, eventBus } = makeHarness([
+      unitEvent({ rawData: { Category: 'Export', 'Frght Kind': 'MTY' } }),
+    ])
+
+    await service.pollAllActiveJobs('ten-1')
+    await service.pollAllActiveJobs('ten-1') // job.emptyReadyAt now set → guard holds
+
+    expect(emitsOf(eventBus, 'terminal_tracking.equipment.empty_ready')).toHaveLength(1)
+  })
+
+  it('does not emit empty_ready when a movement-blocking hold is present', async () => {
+    const { service, eventBus } = makeHarness([
+      unitEvent({
+        rawData: { Category: 'Export', 'Frght Kind': 'MTY' },
+        impediments: ['!EMPTY PERMISSION'],
+      }),
+    ])
+
+    await service.pollAllActiveJobs('ten-1')
+
+    expect(emitsOf(eventBus, 'terminal_tracking.equipment.empty_ready')).toHaveLength(0)
+  })
+
+  it('emits holds_cleared on the blocked → clear transition for an import in the yard', async () => {
+    const existing = [
+      {
+        source: 'terminal',
+        sourceEventId: 'bct:C1:DISC',
+        job: { id: 'job-1' },
+        containerNumber: 'C1',
+        ufvGkey: 'C1',
+        eventDateTime: new Date('2026-06-01T00:00:00Z'),
+        transitState: 'S40_YARD',
+        impediments: ['!CUSTOMS IMPORT PERMISSION'], // was blocked
+        rawData: { Category: 'Import', 'Frght Kind': 'FCL' },
+      },
+    ]
+    const { service, eventBus } = makeHarness(
+      [
+        unitEvent({
+          impediments: null, // now clear
+          rawData: { Category: 'Import', 'Frght Kind': 'FCL' },
+        }),
+      ],
+      existing,
+    )
+
+    await service.pollAllActiveJobs('ten-1')
+
+    const emits = emitsOf(eventBus, 'terminal_tracking.equipment.holds_cleared')
+    expect(emits).toHaveLength(1)
+    expect(emits[0][1]).toMatchObject({ containerNumber: 'C1', holdsCleared: true })
+  })
+
+  it('emits stops_updated when a STOP flag first appears', async () => {
+    const { service, eventBus } = makeHarness([
+      unitEvent({ rawData: { Category: 'Import', 'Frght Kind': 'FCL', 'Stop-Road': 'true' } }),
+    ])
+
+    await service.pollAllActiveJobs('ten-1')
+
+    const emits = emitsOf(eventBus, 'terminal_tracking.equipment.stops_updated')
+    expect(emits).toHaveLength(1)
+    expect(emits[0][1]).toMatchObject({
+      containerNumber: 'C1',
+      stops: { vsl: null, road: true, rail: null },
+    })
+  })
+
+  it('emits stops_updated on a stop-only change (rawData is not in eventSignature)', async () => {
+    const existing = [
+      {
+        source: 'terminal',
+        sourceEventId: 'bct:C1:DISC',
+        job: { id: 'job-1' },
+        containerNumber: 'C1',
+        ufvGkey: 'C1',
+        eventDateTime: DT,
+        eventClassifierCode: 'ACT',
+        transitState: 'S40_YARD',
+        visitState: null,
+        impediments: null,
+        rawData: { Category: 'Import', 'Frght Kind': 'FCL', 'Stop-Road': 'false' },
+      },
+    ]
+    const { service, eventBus } = makeHarness(
+      [unitEvent({ rawData: { Category: 'Import', 'Frght Kind': 'FCL', 'Stop-Road': 'true' } })],
+      existing,
+    )
+
+    await service.pollAllActiveJobs('ten-1')
+
+    const emits = emitsOf(eventBus, 'terminal_tracking.equipment.stops_updated')
+    expect(emits).toHaveLength(1)
+    expect(emits[0][1].stops).toMatchObject({ road: true })
+  })
+
+  it('does not re-emit stops_updated when the stop set is unchanged', async () => {
+    const existing = [
+      {
+        source: 'terminal',
+        sourceEventId: 'bct:C1:DISC',
+        job: { id: 'job-1' },
+        containerNumber: 'C1',
+        ufvGkey: 'C1',
+        eventDateTime: DT,
+        eventClassifierCode: 'ACT',
+        transitState: 'S40_YARD',
+        visitState: null,
+        impediments: null,
+        rawData: { Category: 'Import', 'Frght Kind': 'FCL', 'Stop-Road': 'true' },
+      },
+    ]
+    const { service, eventBus } = makeHarness(
+      [unitEvent({ rawData: { Category: 'Import', 'Frght Kind': 'FCL', 'Stop-Road': 'true' } })],
+      existing,
+    )
+
+    await service.pollAllActiveJobs('ten-1')
+
+    expect(emitsOf(eventBus, 'terminal_tracking.equipment.stops_updated')).toHaveLength(0)
+  })
+
+  it('does not emit holds_cleared when the container was never blocked', async () => {
+    const existing = [
+      {
+        source: 'terminal',
+        sourceEventId: 'bct:C1:DISC',
+        job: { id: 'job-1' },
+        containerNumber: 'C1',
+        ufvGkey: 'C1',
+        eventDateTime: new Date('2026-06-01T00:00:00Z'),
+        transitState: 'S30_ECIN', // different state → signature differs, marked updated
+        impediments: null, // never blocked
+        rawData: { Category: 'Import', 'Frght Kind': 'FCL' },
+      },
+    ]
+    const { service, eventBus } = makeHarness(
+      [unitEvent({ impediments: null, rawData: { Category: 'Import', 'Frght Kind': 'FCL' } })],
+      existing,
+    )
+
+    await service.pollAllActiveJobs('ten-1')
+
+    expect(emitsOf(eventBus, 'terminal_tracking.equipment.holds_cleared')).toHaveLength(0)
+  })
+})

package/src/modules/terminal_tracking/services/__tests__/createJob.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, vi } from 'vitest'
+import { TerminalTrackingService } from '../terminalTrackingService'
+
+const INPUT = {
+  organizationId: 'org-1',
+  tenantId: 'ten-1',
+  terminalCode: 'bct',
+  containerNumber: 'GCXU5598460',
+}
+
+// Mock em whose findOne respects the reuse query's status filter, simulating a
+// DB that holds exactly one job for this container in `dbJob.status`.
+function makeService(dbJob: { id: string; status: string } | null) {
+  const fork = {
+    findOne: vi.fn(async (_entity: any, where: any) => {
+      const statuses: string[] = where?.status?.$in ?? []
+      return dbJob && statuses.includes(dbJob.status) ? dbJob : null
+    }),
+    create: vi.fn((_entity: any, data: any) => ({ id: 'new-job', ...data })),
+    flush: vi.fn(async () => {}),
+  }
+  const em = { fork: () => fork }
+  const eventBus = { emit: vi.fn(async () => {}) }
+  const service = new TerminalTrackingService({
+    em: () => em as never,
+    eventBus: eventBus as never,
+    terminalRegistry: { get: () => undefined } as never,
+    cacheService: { get: async () => null, set: async () => {} } as never,
+  })
+  return { service, fork, eventBus }
+}
+
+describe('createJob reuse', () => {
+  it('creates a NEW job when the same container only has a completed job (returns later)', async () => {
+    const { service, fork, eventBus } = makeService({ id: 'old-job', status: 'completed' })
+    const poll = vi.spyOn(service, 'pollJob')
+
+    const res = await service.createJob(INPUT as never)
+
+    expect(poll).not.toHaveBeenCalled() // not revived
+    expect(fork.create).toHaveBeenCalledTimes(1) // fresh job
+    expect(res.trackingJobId).toBe('new-job')
+    expect(eventBus.emit).toHaveBeenCalledWith(
+      'terminal_tracking.tracking_job.created',
+      expect.any(Object),
+    )
+  })
+
+  it('reuses an existing active job (no duplicate in-flight track)', async () => {
+    const { service, fork } = makeService({ id: 'old-job', status: 'active' })
+    const poll = vi.spyOn(service, 'pollJob').mockResolvedValue({ newEvents: 0, updatedEvents: 0 })
+
+    const res = await service.createJob(INPUT as never)
+
+    expect(poll).toHaveBeenCalledWith('old-job')
+    expect(fork.create).not.toHaveBeenCalled()
+    expect(res.trackingJobId).toBe('old-job')
+  })
+})

package/src/modules/terminal_tracking/services/__tests__/pollAllBatch.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { checkRateLimit, findOneWithDecryption } = vi.hoisted(() => ({
+  checkRateLimit: vi.fn(),
+  findOneWithDecryption: vi.fn(),
+}))
+vi.mock('../../lib/rate-limiter', () => ({ checkRateLimit }))
+vi.mock('@open-mercato/shared/lib/encryption/find', () => ({ findOneWithDecryption }))
+
+import { TerminalTrackingService } from '../terminalTrackingService'
+
+const CONFIG = {
+  terminalCode: 'bct',
+  adapterType: 'n4',
+  displayName: 'Baltic Hub',
+  baseUrl: 'https://api2.baltichub.com/V1/',
+  endpoints: { unit: '/unit', vessel: '/VESSEL' },
+  authType: 'oauth2_password',
+  tokenUrl: null,
+  scope: null,
+  clientId: null,
+  authConfig: null,
+  rateLimitRequests: 200,
+  rateLimitWindowSeconds: 60,
+  unlocode: 'PLGDN',
+  smdgCodes: ['GDNBCT'],
+  bicCodes: [],
+  vesselCacheTtlSeconds: null,
+}
+
+// Three containers at one terminal; c1 and c2 share vessel visit A, c3 on B.
+const VISIT_BY_CONTAINER: Record<string, string> = {
+  C1: '26AAAA001',
+  C2: '26AAAA001',
+  C3: '26BBBB002',
+}
+
+function jobs() {
+  return ['C1', 'C2', 'C3'].map((cn, i) => ({
+    id: `job-${i + 1}`,
+    organizationId: 'org-1',
+    tenantId: 'ten-1',
+    terminalCode: 'bct',
+    containerNumber: cn,
+    schedule: null,
+    status: 'active',
+  }))
+}
+
+function makeHarness() {
+  const fetchEventsBatch = vi.fn(async ({ containerNumbers }: { containerNumbers: string[] }) => ({
+    events: containerNumbers.map((cn) => ({
+      source: 'terminal',
+      sourceEventId: `bct:${cn}:DEPA`,
+      eventType: 'EQUIPMENT',
+      eventCode: 'DISC',
+      eventClassifierCode: 'ACT',
+      eventDateTime: new Date('2026-06-03T01:58:00Z'),
+      containerNumber: cn,
+      ufvGkey: cn,
+      visitRefIn: VISIT_BY_CONTAINER[cn],
+      visitRefOut: 'GEN_TRUCK',
+      rawData: { Category: 'Import' }, // import leg → vessel on I/B
+    })),
+  }))
+  const fetchVesselVisit = vi.fn(async ({ visitRef }: { visitRef: string }) => ({
+    visitRef,
+    vesselName: `VESSEL ${visitRef}`,
+    ibVoyage: '623N',
+    obVoyage: '625S',
+    line: 'MAE',
+    phase: 'Inbound',
+    eta: new Date('2026-06-14T10:00:00Z'),
+    etd: null,
+    ata: null,
+    atd: null,
+    beginReceive: null,
+    dryCutoff: null,
+    rawData: null,
+  }))
+  const adapter = {
+    adapterType: 'n4',
+    defaultEndpoints: { unit: '/unit', vessel: '/VESSEL' },
+    fetchEvents: vi.fn(),
+    fetchEventsBatch,
+    fetchVesselVisit,
+    testConnection: vi.fn(),
+  }
+
+  const em = {
+    fork() {
+      return this
+    },
+    async find(_entity: any, where: any) {
+      if (where && 'status' in where) return jobs() // due jobs
+      return [] // vessel cache miss + no existing events
+    },
+    create(_entity: any, data: any) {
+      return { ...data }
+    },
+    async flush() {},
+  }
+
+  const eventBus = { emit: vi.fn(async () => {}) }
+  const service = new TerminalTrackingService({
+    em: () => em as never,
+    eventBus: eventBus as never,
+    terminalRegistry: { get: () => adapter } as never,
+    cacheService: { get: async () => null, set: async () => {} } as never,
+  })
+  return { service, adapter, fetchEventsBatch, fetchVesselVisit, eventBus }
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  checkRateLimit.mockResolvedValue({ allowed: true })
+  findOneWithDecryption.mockResolvedValue({ ...CONFIG })
+})
+
+describe('pollAllActiveJobs batching', () => {
+  it('fetches all containers in one /unit call and resolves each vessel once', async () => {
+    const { service, fetchEventsBatch, fetchVesselVisit, eventBus } = makeHarness()
+
+    const res = await service.pollAllActiveJobs('ten-1')
+
+    // One batched /unit call for all three containers.
+    expect(fetchEventsBatch).toHaveBeenCalledTimes(1)
+    expect(fetchEventsBatch.mock.calls[0][0].containerNumbers).toEqual(['C1', 'C2', 'C3'])
+
+    // Two unique vessel visits (A shared by C1+C2, B for C3) → two fetches.
+    expect(fetchVesselVisit).toHaveBeenCalledTimes(2)
+    const fetchedRefs = fetchVesselVisit.mock.calls.map((c) => c[0].visitRef).sort()
+    expect(fetchedRefs).toEqual(['26AAAA001', '26BBBB002'])
+
+    // One terminal event emitted per container.
+    const created = eventBus.emit.mock.calls.filter((c) => c[0] === 'terminal_tracking.terminal_event.created')
+    expect(created).toHaveLength(3)
+    expect(res).toMatchObject({ polled: 3, newEvents: 3 })
+  })
+
+  it('minimises rate-limit spend: 1 unit token + 2 vessel tokens, not 3 unit calls', async () => {
+    const { service } = makeHarness()
+    await service.pollAllActiveJobs('ten-1')
+    // 1 (unit batch) + 2 (unique vessels) = 3 — versus 3 unit + 3 vessel pre-batching.
+    expect(checkRateLimit).toHaveBeenCalledTimes(3)
+  })
+})

package/src/modules/terminal_tracking/services/__tests__/terminalMatcher.test.ts

@@ -0,0 +1,70 @@
+import { TerminalMatcherService } from '../terminalMatcherService'
+
+const SCOPE = { organizationId: 'org-1', tenantId: 'ten-1' }
+
+const CONFIGS = [
+  {
+    terminalCode: 'bct',
+    displayName: 'Baltic Hub',
+    unlocode: 'PLGDN',
+    bicCodes: ['BCTGDN'],
+    smdgCodes: ['GDNBCT'],
+    nameAliases: ['BCT', 'DCT Gdansk'],
+    isActive: true,
+  },
+  {
+    terminalCode: 'gct',
+    displayName: 'Gdynia Container Terminal',
+    unlocode: 'PLGDY',
+    bicCodes: [],
+    smdgCodes: ['GDYGCT'],
+    nameAliases: ['GCT'],
+    isActive: true,
+  },
+]
+
+function makeService(configs: unknown[] = CONFIGS) {
+  const em = () => ({ fork: () => ({ find: async () => configs }) })
+  return new TerminalMatcherService({ em: em as never })
+}
+
+describe('TerminalMatcherService.resolveFacility', () => {
+  it('matches by exact BIC (case-insensitive)', async () => {
+    const m = await makeService().resolveFacility({ bic: 'bctgdn' }, SCOPE)
+    expect(m).toMatchObject({ terminalCode: 'bct', matchedBy: 'bic' })
+  })
+
+  it('matches by exact SMDG', async () => {
+    const m = await makeService().resolveFacility({ smdg: 'GDYGCT' }, SCOPE)
+    expect(m).toMatchObject({ terminalCode: 'gct', matchedBy: 'smdg' })
+  })
+
+  it('matches by exact UNLOCODE (case-insensitive)', async () => {
+    const m = await makeService().resolveFacility({ unlocode: 'plgdn' }, SCOPE)
+    expect(m).toMatchObject({ terminalCode: 'bct', matchedBy: 'unlocode' })
+  })
+
+  it('matches by fuzzy display name', async () => {
+    const m = await makeService().resolveFacility({ name: 'baltic hub' }, SCOPE)
+    expect(m).toMatchObject({ terminalCode: 'bct', matchedBy: 'name' })
+  })
+
+  it('matches by fuzzy alias', async () => {
+    const m = await makeService().resolveFacility({ name: 'DCT Gdańsk'.replace('ń', 'n') }, SCOPE)
+    expect(m?.terminalCode).toBe('bct')
+  })
+
+  it('prefers exact BIC over a fuzzy name on a different terminal', async () => {
+    const m = await makeService().resolveFacility({ bic: 'BCTGDN', name: 'Gdynia' }, SCOPE)
+    expect(m).toMatchObject({ terminalCode: 'bct', matchedBy: 'bic' })
+  })
+
+  it('returns null when nothing matches', async () => {
+    expect(await makeService().resolveFacility({ name: 'Rotterdam APM Maasvlakte' }, SCOPE)).toBeNull()
+    expect(await makeService().resolveFacility({ bic: 'NOPE' }, SCOPE)).toBeNull()
+  })
+
+  it('returns null when there are no configured terminals', async () => {
+    expect(await makeService([]).resolveFacility({ unlocode: 'PLGDN' }, SCOPE)).toBeNull()
+  })
+})