@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/i18n/pl.json

@@ -0,0 +1,206 @@
+{
+  "terminal_tracking": {
+    "title": "Śledzenie terminali",
+    "stops": {
+      "title": "Ograniczenia załadunku",
+      "vsl": "Brak załadunku na statek",
+      "road": "Brak podjęcia drogowego",
+      "rail": "Brak podjęcia kolejowego"
+    },
+    "nav": {
+      "group": "Śledzenie terminali",
+      "terminal_configs": "Terminale",
+      "tracking_jobs": "Śledzone kontenery"
+    },
+    "errors": {
+      "tenant_required": "Wymagany jest kontekst najemcy",
+      "organization_required": "Wymagany jest kontekst organizacji"
+    },
+    "terminal_config": {
+      "title": "Konfiguracje terminali",
+      "displayName": "Nazwa",
+      "terminalCode": "Kod terminalu",
+      "adapterType": "Adapter",
+      "baseUrl": "Bazowy adres API",
+      "proxyUrl": "Adres proxy API (opcjonalnie)",
+      "unlocode": "UN/LOCODE",
+      "smdgCodes": "Kody SMDG (po przecinku)",
+      "bicCodes": "Kody BIC (po przecinku)",
+      "nameAliases": "Aliasy nazwy (po przecinku)",
+      "tokenUrl": "Adres URL tokenu",
+      "scope": "Zakres (scope)",
+      "clientId": "Identyfikator klienta",
+      "rateLimitRequests": "Limit zapytań",
+      "rateLimitWindowSeconds": "Okno (sekundy)",
+      "isActive": "Aktywny",
+      "unchanged": "bez zmian",
+      "credEditHint": "Pozostaw dane uwierzytelniające puste, aby ich nie zmieniać.",
+      "gctHint": "Klucz (base32) widoczny w panelu GCT obok kodu QR. Na jego podstawie przy każdym logowaniu obliczany jest aktualny kod jednorazowy.",
+      "section": {
+        "terminal": "Terminal",
+        "auth": "Uwierzytelnianie",
+        "matching": "Dopasowanie",
+        "advanced": "Zaawansowane"
+      },
+      "cred": {
+        "username": "Nazwa użytkownika",
+        "password": "Hasło",
+        "clientSecret": "Sekret klienta",
+        "companyCode": "Kod firmy",
+        "loginName": "Login",
+        "totpSecret": "Twój sekret 2FA"
+      },
+      "validation": {
+        "allCredentials": "Wprowadź wszystkie pola danych uwierzytelniających",
+        "credentialsRequired": "Dane uwierzytelniające są wymagane"
+      }
+    },
+    "tracking_job": {
+      "title": "Zadania śledzenia terminali",
+      "containerNumber": "Kontener",
+      "status": "Status",
+      "gateIn": "Wjazd",
+      "gateOut": "Wyjazd",
+      "holds": "Blokady",
+      "lastPollAt": "Ostatnie odpytanie",
+      "details": "Szczegóły kontenera",
+      "noEvents": "Brak zdarzeń terminalowych. Użyj „Odpytaj teraz”, aby pobrać.",
+      "leg": "Wizyta na terminalu",
+      "recentErrors": "Ostatnie błędy odpytania",
+      "jobInfo": "Śledzenie",
+      "nextPollAt": "Następne odpytanie",
+      "retryCount": "Ponowienia",
+      "jobId": "ID zadania",
+      "actions": {
+        "details": "Szczegóły",
+        "poll": "Odpytaj teraz"
+      },
+      "flash": {
+        "polled": "Odpytano — {n} nowych, {u} zaktualizowanych zdarzeń"
+      },
+      "statuses": {
+        "active": "Aktywny",
+        "paused": "Wstrzymany",
+        "deactivated": "Dezaktywowany",
+        "failed": "Błąd",
+        "completed": "Zakończony"
+      }
+    },
+    "event": {
+      "source_badge": "Terminal",
+      "yardPosition": "Pozycja na placu",
+      "vgm": "VGM (kg)",
+      "visitPhase": "Faza wizyty",
+      "impediments": "Blokady",
+      "seals": "Plomby",
+      "eta": "ETA",
+      "etd": "ETD",
+      "ata": "ATA",
+      "atd": "ATD",
+      "gate_in": "Wjazd (brama)",
+      "yard": "Na placu / rozładowany",
+      "loaded": "Załadowany",
+      "loadedAt": "Data załadunku",
+      "departed": "Wyjazd",
+      "ufvGkey": "Ufv_Gkey",
+      "rawData": "Surowe dane terminalu"
+    },
+    "holds": {
+      "unknown": {
+        "label": "Nieznana blokada",
+        "description": "Nierozpoznana blokada terminalowa. Szczegóły uzyskasz w terminalu.",
+        "resolution": "Skontaktuj się z terminalem, aby ustalić sposób zdjęcia blokady."
+      },
+      "cfs_appointment": {
+        "label": "Awizacja CFS",
+        "description": "Nakładana podczas przyjmowania zlecenia importowego przez magazyn CFS.",
+        "resolution": "Zdejmowana automatycznie po zrealizowaniu zlecenia i pracy magazynu."
+      },
+      "customs_import_permission": {
+        "label": "Pozwolenie celne (import)",
+        "description": "Nakładana systemowo na wszystkie kontenery importowe oczekujące na zwolnienie celne.",
+        "resolution": "Zdejmowana automatycznie po aktualizacji numeru MRN przy użyciu polskich kodów PCS."
+      },
+      "customs_import_hold": {
+        "label": "Blokada celna (import)",
+        "description": "Nakładana ręcznie przez funkcjonariusza celnego w celu skanowania, kontroli lub z powodu problemu z odprawą.",
+        "resolution": "Może ją zdjąć wyłącznie funkcjonariusz celny — skontaktuj się z urzędem celnym."
+      },
+      "line_import_permission": {
+        "label": "Pozwolenie armatora (import)",
+        "description": "Nakładana systemowo na wszystkie kontenery importowe do czasu zwolnienia przez armatora.",
+        "resolution": "Zdejmowana po zwolnieniu kontenera przez armatora numerem PIN."
+      },
+      "oog_hold": {
+        "label": "Blokada OOG",
+        "description": "Nakładana na ponadgabarytowe kontenery importowe wymagające specjalnych zezwoleń.",
+        "resolution": "Wymaga weryfikacji przez Baltic Hub przed odbiorem; do tego czasu kontener nie może zostać awizowany do odbioru."
+      },
+      "cfs_hold": {
+        "label": "Blokada CFS",
+        "description": "Nakładana podczas przyjmowania zlecenia eksportowego przez magazyn CFS.",
+        "resolution": "Zdejmowana automatycznie po zrealizowaniu zlecenia i pracy magazynu."
+      },
+      "customs_export_permission": {
+        "label": "Pozwolenie celne (eksport)",
+        "description": "Nakładana systemowo na kontenery eksportowe oczekujące na zwolnienie celne.",
+        "resolution": "Zdejmowana automatycznie po aktualizacji MRN; musi zostać zdjęta przed terminem odprawy celnej."
+      },
+      "customs_export_hold": {
+        "label": "Blokada celna (eksport)",
+        "description": "Nakładana ręcznie przez funkcjonariusza celnego w celu skanowania, kontroli lub z powodu problemu z odprawą.",
+        "resolution": "Może ją zdjąć wyłącznie funkcjonariusz celny — skontaktuj się z urzędem celnym."
+      },
+      "unit_vgm_load_permission": {
+        "label": "Pozwolenie VGM na załadunek",
+        "description": "Nakładana na wszystkie pełne kontenery eksportowe bez zweryfikowanej masy brutto (VGM).",
+        "resolution": "Zdejmowana po wprowadzeniu masy VGM do systemu Navis."
+      },
+      "dgd_hold": {
+        "label": "Blokada DGD",
+        "description": "Nakładana automatycznie na wszystkie kontenery eksportowe z ładunkiem IMO (niebezpiecznym).",
+        "resolution": "Wymaga złożenia dokumentu DGD (deklaracji ładunku niebezpiecznego)."
+      },
+      "scanning_hold": {
+        "label": "Blokada skanowania",
+        "description": "Nakładana ręcznie przez funkcjonariusza celnego; kontener musi zostać przedstawiony do skanowania.",
+        "resolution": "Zdejmowana przez służby celne po skanowaniu (wybór DCT_CFS_SCANNING)."
+      },
+      "empty_permission": {
+        "label": "Pozwolenie (pusty)",
+        "description": "Nakładana systemowo na wszystkie puste kontenery oczekujące na referencję zwolnienia.",
+        "resolution": "Zdejmowana po podaniu numeru EDO / bookingu od armatora."
+      },
+      "missing_agent_permission": {
+        "label": "Brak pozwolenia agenta",
+        "description": "Dotyczy nieaktywnej płatności PCS. Obecnie nie blokuje załadunku na statek ani odbioru.",
+        "resolution": "Zdejmowana po wpisaniu kodu armatora w polu Agent One."
+      },
+      "technical_full_container": {
+        "label": "Techniczna (pełny kontener)",
+        "description": "Nakładana na wszystkie pełne kontenery importowe/eksportowe w celu obsługi rozpoznawania znaków OCR. Nie blokuje ruchu.",
+        "resolution": "Nie wymaga działań — wyłącznie informacyjna."
+      },
+      "technical_live_reefer": {
+        "label": "Techniczna (aktywny reefer)",
+        "description": "Nakładana na wszystkie pełne kontenery chłodnicze w celu obsługi OCR. Nie blokuje operacji.",
+        "resolution": "Nie wymaga działań — wyłącznie informacyjna."
+      },
+      "terminal_hold": {
+        "label": "Blokada terminalowa",
+        "description": "Nakładana z powodu nieprawidłowości kontenera (błędne oznakowanie, wygięte belki kontenera itp.).",
+        "resolution": "Skontaktuj się z Biurem Obsługi Klienta Baltic Hub."
+      },
+      "czrm_hold": {
+        "label": "Blokada CZRM",
+        "description": "Nakładana przez urząd celny.",
+        "resolution": "Skontaktuj się bezpośrednio z urzędem celnym w celu jej zdjęcia."
+      },
+      "izrx_hold": {
+        "label": "Blokada IZRX",
+        "description": "Nakładana przez urząd celny.",
+        "resolution": "Skontaktuj się bezpośrednio z urzędem celnym w celu jej zdjęcia."
+      }
+    }
+  }
+}

package/src/modules/terminal_tracking/index.ts

@@ -0,0 +1,13 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+import './commands'
+
+export const metadata: ModuleInfo = {
+  name: 'terminal_tracking',
+  title: 'Terminal Tracking',
+  version: '0.1.0',
+  description: 'Container terminal (Navis N4) tracking with per-terminal config, periodic polling, and events.',
+  author: 'FreightTech',
+  license: 'Proprietary',
+}
+
+export { features } from './acl'

package/src/modules/terminal_tracking/lib/__tests__/availability.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest'
+import {
+  blockingHoldCount,
+  impedimentsChanged,
+  isEmptyReady,
+  isImportHoldsCleared,
+  type AvailabilityInput,
+} from '../availability'
+
+// Catalogue references (see ../holds.ts):
+// - blocking:     CUSTOMS IMPORT PERMISSION, LINE IMPORT PERMISSION, EMPTY PERMISSION
+// - non-blocking: TECHNICAL FULL CONTAINER, MISSING AGENT PERMISSION
+const BLOCKING = '!CUSTOMS IMPORT PERMISSION'
+const BLOCKING_2 = '!LINE IMPORT PERMISSION'
+const EMPTY_PERMISSION = '!EMPTY PERMISSION'
+const NON_BLOCKING = '!TECHNICAL_FULL_CONTAINER'
+
+function evt(
+  category: string,
+  frghtKind: 'MTY' | 'Empty' | 'FCL',
+  transitState: string,
+  impediments: string[] | null,
+  extraRaw: Record<string, unknown> = {},
+): AvailabilityInput {
+  return {
+    transitState,
+    impediments,
+    rawData: { Category: category, 'Frght Kind': frghtKind, ...extraRaw },
+  }
+}
+
+describe('blockingHoldCount', () => {
+  it('counts only movement-blocking holds', () => {
+    expect(blockingHoldCount([BLOCKING, NON_BLOCKING])).toBe(1)
+    expect(blockingHoldCount([BLOCKING, BLOCKING_2])).toBe(2)
+    expect(blockingHoldCount([NON_BLOCKING])).toBe(0)
+    expect(blockingHoldCount([])).toBe(0)
+    expect(blockingHoldCount(null)).toBe(0)
+  })
+})
+
+describe('isEmptyReady', () => {
+  it('fires for an empty in the yard with no blocking holds', () => {
+    expect(isEmptyReady(evt('Export', 'MTY', 'S40_YARD', null))).toBe(true)
+  })
+
+  it('recognises the real Baltic Hub empty value "Empty" (not just "MTY")', () => {
+    expect(isEmptyReady(evt('Storage', 'Empty', 'S40_YARD', null))).toBe(true)
+  })
+
+  it('fires regardless of category (empties sit under N4 "Storage")', () => {
+    expect(isEmptyReady(evt('Storage', 'MTY', 'S40_YARD', null))).toBe(true)
+    expect(isEmptyReady(evt('Import', 'MTY', 'S40_YARD', null))).toBe(true)
+  })
+
+  it('fires when only non-blocking holds are present (incl. the real REFFER spelling)', () => {
+    expect(isEmptyReady(evt('Storage', 'MTY', 'S40_YARD', [NON_BLOCKING]))).toBe(true)
+    expect(isEmptyReady(evt('Storage', 'MTY', 'S40_YARD', ['!TECHNICAL LIVE REFFER']))).toBe(true)
+  })
+
+  it('does not fire while EMPTY PERMISSION (or any blocking hold) is present', () => {
+    expect(isEmptyReady(evt('Storage', 'MTY', 'S40_YARD', [EMPTY_PERMISSION]))).toBe(false)
+  })
+
+  it('does not fire for a full container', () => {
+    expect(isEmptyReady(evt('Export', 'FCL', 'S40_YARD', null))).toBe(false)
+  })
+
+  it('does not fire when not yet in the yard', () => {
+    expect(isEmptyReady(evt('Storage', 'MTY', 'S20_INBOUND', null))).toBe(false)
+  })
+
+  it('does not fire while road pickup is explicitly stopped (Stop-Road)', () => {
+    expect(isEmptyReady(evt('Storage', 'MTY', 'S40_YARD', null, { 'Stop-Road': 'Y' }))).toBe(false)
+  })
+
+  it('still fires when Stop-Road is present but not active, or an unrelated stop is set', () => {
+    expect(isEmptyReady(evt('Storage', 'MTY', 'S40_YARD', null, { 'Stop-Road': 'N' }))).toBe(true)
+    expect(isEmptyReady(evt('Storage', 'MTY', 'S40_YARD', null, { 'Stop-Vsl': 'Y' }))).toBe(true)
+  })
+})
+
+describe('isImportHoldsCleared', () => {
+  it('fires on the blocked → clear transition for an import in the yard', () => {
+    const e = evt('Import', 'FCL', 'S40_YARD', [])
+    expect(isImportHoldsCleared(e, [BLOCKING])).toBe(true)
+  })
+
+  it('does not fire for a container that was never blocked', () => {
+    const e = evt('Import', 'FCL', 'S40_YARD', [])
+    expect(isImportHoldsCleared(e, [])).toBe(false)
+    expect(isImportHoldsCleared(e, [NON_BLOCKING])).toBe(false)
+  })
+
+  it('does not fire while a blocking hold remains', () => {
+    const e = evt('Import', 'FCL', 'S40_YARD', [BLOCKING_2])
+    expect(isImportHoldsCleared(e, [BLOCKING])).toBe(false)
+  })
+
+  it('does not fire when not in the yard', () => {
+    const e = evt('Import', 'FCL', 'S20_INBOUND', [])
+    expect(isImportHoldsCleared(e, [BLOCKING])).toBe(false)
+  })
+
+  it('does not fire for an export leg', () => {
+    const e = evt('Export', 'FCL', 'S40_YARD', [])
+    expect(isImportHoldsCleared(e, [BLOCKING])).toBe(false)
+  })
+
+  it('still fires under a road stop — the transition event is not gated (would be lost, not delayed)', () => {
+    const e = evt('Import', 'FCL', 'S40_YARD', [], { 'Stop-Road': 'Y' })
+    expect(isImportHoldsCleared(e, [BLOCKING])).toBe(true)
+  })
+})
+
+describe('impedimentsChanged', () => {
+  it('detects an added hold', () => {
+    expect(impedimentsChanged([BLOCKING], [BLOCKING, BLOCKING_2])).toBe(true)
+  })
+
+  it('detects a removed hold', () => {
+    expect(impedimentsChanged([BLOCKING, BLOCKING_2], [BLOCKING])).toBe(true)
+  })
+
+  it('treats a null/absent prior with current holds as a change (first appearance)', () => {
+    expect(impedimentsChanged(null, [BLOCKING])).toBe(true)
+    expect(impedimentsChanged(undefined, [BLOCKING])).toBe(true)
+  })
+
+  it('is false when nothing changed (order- and duplicate-insensitive)', () => {
+    expect(impedimentsChanged([BLOCKING, BLOCKING_2], [BLOCKING_2, BLOCKING])).toBe(false)
+    expect(impedimentsChanged([BLOCKING, BLOCKING], [BLOCKING])).toBe(false)
+    expect(impedimentsChanged(null, [])).toBe(false)
+    expect(impedimentsChanged([], null)).toBe(false)
+  })
+})

package/src/modules/terminal_tracking/lib/__tests__/ensure-schedule.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi } from 'vitest'
+import { ensureTerminalPollSchedule } from '../ensure-schedule'
+
+const scope = {
+  organizationId: '942dbb1e-ff24-430b-bd9b-af1aed4d28e9',
+  tenantId: '60e4e4d2-5765-40c2-9075-33a1a2aed068',
+}
+
+function makeContainer(scheduler: unknown) {
+  return {
+    resolve: <T = unknown>(_name: string) => scheduler as T,
+  }
+}
+
+describe('ensureTerminalPollSchedule (create-only)', () => {
+  it('does not register when the schedule already exists (preserves UI edits)', async () => {
+    const register = vi.fn().mockResolvedValue(undefined)
+    const exists = vi.fn().mockResolvedValue(true)
+
+    await ensureTerminalPollSchedule(makeContainer({ register, exists }), scope)
+
+    expect(exists).toHaveBeenCalledTimes(1)
+    expect(register).not.toHaveBeenCalled()
+  })
+
+  it('registers with module defaults when the schedule is missing', async () => {
+    const register = vi.fn().mockResolvedValue(undefined)
+    const exists = vi.fn().mockResolvedValue(false)
+
+    await ensureTerminalPollSchedule(makeContainer({ register, exists }), scope)
+
+    expect(register).toHaveBeenCalledTimes(1)
+    const reg = register.mock.calls[0][0] as Record<string, unknown>
+    // Same id is passed to exists() and register() so the guard is reliable.
+    expect(reg.id).toBe(exists.mock.calls[0][0])
+    expect(reg.scheduleType).toBe('cron')
+    expect(reg.scheduleValue).toBe('0 */4 * * *')
+    expect(reg.targetCommand).toBe('terminal_tracking.tracking.poll_all')
+  })
+
+  it('falls back to register when the existence check throws', async () => {
+    const register = vi.fn().mockResolvedValue(undefined)
+    const exists = vi.fn().mockRejectedValue(new Error('boom'))
+
+    await ensureTerminalPollSchedule(makeContainer({ register, exists }), scope)
+
+    expect(register).toHaveBeenCalledTimes(1)
+  })
+
+  it('registers when the scheduler has no exists() method (older scheduler)', async () => {
+    const register = vi.fn().mockResolvedValue(undefined)
+
+    await ensureTerminalPollSchedule(makeContainer({ register }), scope)
+
+    expect(register).toHaveBeenCalledTimes(1)
+  })
+
+  it('no-ops when the scheduler module is not installed', async () => {
+    const container = {
+      resolve: () => {
+        throw new Error('not registered')
+      },
+    }
+
+    await expect(ensureTerminalPollSchedule(container, scope)).resolves.toBeUndefined()
+  })
+})

package/src/modules/terminal_tracking/lib/__tests__/holds.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest'
+import {
+  normalizeHoldCode,
+  getHoldInfo,
+  resolveHolds,
+  highestHoldSeverity,
+} from '../holds'
+
+describe('normalizeHoldCode', () => {
+  it('strips the leading "!" and upper-cases', () => {
+    expect(normalizeHoldCode('!dgd hold')).toBe('DGD HOLD')
+  })
+
+  it('treats underscore- and space-delimited codes identically', () => {
+    expect(normalizeHoldCode('!TECHNICAL_FULL_CONTAINER')).toBe('TECHNICAL FULL CONTAINER')
+    expect(normalizeHoldCode('TECHNICAL FULL CONTAINER')).toBe('TECHNICAL FULL CONTAINER')
+  })
+})
+
+describe('getHoldInfo', () => {
+  it('resolves a known critical hold with its explanation', () => {
+    const info = getHoldInfo('!CUSTOMS EXPORT HOLD')
+    expect(info.unknown).toBe(false)
+    expect(info.severity).toBe('critical')
+    expect(info.blocksMovement).toBe(true)
+    expect(info.category).toBe('export')
+    expect(info.rawCode).toBe('!CUSTOMS EXPORT HOLD')
+    expect(info.resolution).toMatch(/customs officer/i)
+  })
+
+  it('classifies OCR technical holds as non-blocking info', () => {
+    const info = getHoldInfo('!TECHNICAL_FULL_CONTAINER')
+    expect(info.severity).toBe('info')
+    expect(info.blocksMovement).toBe(false)
+  })
+
+  it('falls back to a visible warning for unknown codes and shows the raw hold', () => {
+    const info = getHoldInfo('!SOME_NEW_HOLD')
+    expect(info.unknown).toBe(true)
+    expect(info.severity).toBe('warning')
+    expect(info.i18nKey).toBe('unknown')
+    // Label echoes the raw hold (minus the `!`), not a normalized form.
+    expect(info.label).toBe('SOME_NEW_HOLD')
+    expect(info.rawCode).toBe('!SOME_NEW_HOLD')
+  })
+})
+
+describe('resolveHolds', () => {
+  it('sorts most-urgent first and drops empties', () => {
+    const holds = resolveHolds([
+      '!TECHNICAL_FULL_CONTAINER',
+      '',
+      '!CUSTOMS EXPORT PERMISSION',
+      '!DGD HOLD',
+    ])
+    expect(holds.map((h) => h.severity)).toEqual(['critical', 'warning', 'info'])
+  })
+
+  it('returns an empty array for null/empty input', () => {
+    expect(resolveHolds(null)).toEqual([])
+    expect(resolveHolds([])).toEqual([])
+  })
+})
+
+describe('highestHoldSeverity', () => {
+  it('returns the top severity', () => {
+    expect(highestHoldSeverity(['!TECHNICAL_FULL_CONTAINER', '!DGD HOLD'])).toBe('critical')
+  })
+
+  it('returns null when there are no holds', () => {
+    expect(highestHoldSeverity([])).toBeNull()
+  })
+})

package/src/modules/terminal_tracking/lib/__tests__/stops.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest'
+import {
+  parseTerminalStops,
+  isRoadStopped,
+  activeStopModes,
+  stopsChanged,
+  NO_STOPS,
+} from '../stops'
+
+describe('parseTerminalStops', () => {
+  it('returns all-null when no STOP columns are present (pre-update payload)', () => {
+    expect(parseTerminalStops({ 'Unit Nbr': 'ABCU1234567', Category: 'Import' })).toEqual(NO_STOPS)
+    expect(parseTerminalStops(null)).toEqual(NO_STOPS)
+    expect(parseTerminalStops(undefined)).toEqual(NO_STOPS)
+  })
+
+  it('reads the documented Stop-Vsl / Stop-Road / Stop-Rail headers', () => {
+    expect(
+      parseTerminalStops({ 'Stop-Vsl': 'Y', 'Stop-Road': 'Y', 'Stop-Rail': 'Y' }),
+    ).toEqual({ vsl: true, road: true, rail: true })
+  })
+
+  it('distinguishes a present-but-empty column (false) from an absent one (null)', () => {
+    // Stop-Road present with no value -> reported, not stopped; Stop-Vsl absent -> unknown.
+    expect(parseTerminalStops({ 'Stop-Road': null, 'Stop-Rail': '' })).toEqual({
+      vsl: null,
+      road: false,
+      rail: false,
+    })
+  })
+
+  it('matches headers tolerant of casing and punctuation', () => {
+    expect(parseTerminalStops({ 'STOP VSL': 'Y' }).vsl).toBe(true)
+    expect(parseTerminalStops({ StopRoad: '1' }).road).toBe(true)
+    expect(parseTerminalStops({ 'stop_rail': 'true' }).rail).toBe(true)
+    expect(parseTerminalStops({ 'Stop-Vessel': 'Y' }).vsl).toBe(true)
+  })
+
+  it('treats explicit falsy tokens as no-stop', () => {
+    expect(parseTerminalStops({ 'Stop-Road': 'N' }).road).toBe(false)
+    expect(parseTerminalStops({ 'Stop-Road': 'No' }).road).toBe(false)
+    expect(parseTerminalStops({ 'Stop-Road': '0' }).road).toBe(false)
+    expect(parseTerminalStops({ 'Stop-Road': 'false' }).road).toBe(false)
+    expect(parseTerminalStops({ 'Stop-Road': '-' }).road).toBe(false)
+  })
+
+  it('treats any other non-empty value as an active stop (e.g. a timestamp/reason)', () => {
+    expect(parseTerminalStops({ 'Stop-Vsl': '2026-08-04 10:00' }).vsl).toBe(true)
+    expect(parseTerminalStops({ 'Stop-Rail': 'CUSTOMS' }).rail).toBe(true)
+  })
+})
+
+describe('isRoadStopped / activeStopModes', () => {
+  it('isRoadStopped is true only on an explicit road stop', () => {
+    expect(isRoadStopped({ vsl: null, road: true, rail: null })).toBe(true)
+    expect(isRoadStopped({ vsl: null, road: false, rail: null })).toBe(false)
+    expect(isRoadStopped({ vsl: null, road: null, rail: null })).toBe(false)
+  })
+
+  it('lists active modes in vsl -> road -> rail order', () => {
+    expect(activeStopModes({ vsl: true, road: false, rail: true })).toEqual(['vsl', 'rail'])
+    expect(activeStopModes(NO_STOPS)).toEqual([])
+    expect(activeStopModes({ vsl: true, road: true, rail: true })).toEqual(['vsl', 'road', 'rail'])
+  })
+})
+
+describe('stopsChanged', () => {
+  it('detects an active-stop appearing or clearing on any mode', () => {
+    expect(stopsChanged(NO_STOPS, { vsl: null, road: true, rail: null })).toBe(true)
+    expect(stopsChanged({ vsl: null, road: false, rail: null }, { vsl: null, road: true, rail: null })).toBe(true)
+    expect(stopsChanged({ vsl: true, road: null, rail: null }, { vsl: false, road: null, rail: null })).toBe(true)
+  })
+
+  it('treats null (unreported) and false (not stopped) as equivalent — no spurious change', () => {
+    // null → false is NOT a change: neither is an active stop.
+    expect(stopsChanged({ vsl: null, road: null, rail: null }, { vsl: false, road: false, rail: false })).toBe(false)
+    expect(stopsChanged(NO_STOPS, { vsl: null, road: null, rail: null })).toBe(false)
+    expect(stopsChanged({ vsl: true, road: false, rail: null }, { vsl: true, road: null, rail: false })).toBe(false)
+  })
+})

package/src/modules/terminal_tracking/lib/__tests__/totp.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest'
+import { generateTotp, base32Decode, TOTP_PERIOD_SECONDS } from '../totp'
+
+// RFC 6238 Appendix B publishes 8-digit reference codes for the SHA1 seed
+// ASCII "12345678901234567890". Our generator emits 6 digits, i.e. the last 6
+// of each published value. base32("12345678901234567890") = the seed below.
+const RFC_SEED = 'GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ'
+
+describe('generateTotp (RFC 6238 parity)', () => {
+  it('matches the published 6-digit truncations at fixed instants', () => {
+    // T=59s → 94287082 ; T=1234567890s → 89005924
+    expect(generateTotp(RFC_SEED, 59_000)).toBe('287082')
+    expect(generateTotp(RFC_SEED, 1_234_567_890_000)).toBe('005924')
+  })
+
+  it('always returns a zero-padded 6-digit string', () => {
+    for (const t of [0, 30_000, 1_000_000_000_000, Date.now()]) {
+      expect(generateTotp(RFC_SEED, t)).toMatch(/^\d{6}$/)
+    }
+  })
+
+  it('rotates once per 30s period and is stable within one period', () => {
+    const base = 1_700_000_000_000 // arbitrary period boundary-ish
+    const inSamePeriod = generateTotp(RFC_SEED, base)
+    expect(generateTotp(RFC_SEED, base + 1_000)).toBe(inSamePeriod) // same window
+    const next = generateTotp(RFC_SEED, base + TOTP_PERIOD_SECONDS * 1_000)
+    expect(next).not.toBe(inSamePeriod) // next window differs
+  })
+
+  it('decodes base32 case-insensitively and ignoring whitespace', () => {
+    expect(base32Decode('jbswy3dpehpk3pxp')).toEqual(base32Decode('JBSWY3DPEHPK3PXP'))
+    expect(base32Decode('JBSW Y3DP EHPK 3PXP')).toEqual(base32Decode('JBSWY3DPEHPK3PXP'))
+  })
+
+  it('rejects an invalid base32 secret', () => {
+    expect(() => generateTotp('not-base32!!')).toThrow(/base32/)
+  })
+})