@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/lib/adapters/gct/auth/token.ts

@@ -0,0 +1,219 @@
+import type { ResolvedTerminalConfig } from '../../../terminal-adapter'
+import type { GctToken } from '../types'
+import { n4Request } from '../../n4/http'
+import { generateTotp } from '../../../totp'
+
+/**
+ * GCT token acquisition + process-level cache.
+ *
+ * GCT mints a token from a plain `GET /gctapi/Auth/{company}/{login}/{password}`
+ * (credentials in the path — see the security note below), returning an ISO
+ * `expires` instant. The token is then replayed in the `Authorization` header on
+ * every data call. This mirrors `../../n4/auth/ropc.ts` in shape (cache keyed by
+ * principal, 30s safety margin, invalidate-on-401) but not in wire protocol.
+ *
+ * LIFECYCLE: a cached token is reused until 30s before `expires`. Once it lapses
+ * we first try to REFRESH it via the keep-alive endpoint (`GET /gctapi/ping`,
+ * current token in the header) — cheap, no 2FA code — and only RE-AUTHENTICATE
+ * (mint a new token with a fresh authenticator code) when the refresh fails.
+ *
+ * AUTH: GCT's login expects an authenticator one-time code where a password would
+ * normally go. We store the base32 authenticator *secret* (the seed behind the
+ * enrollment QR) in `auth_config` and derive the current 6-digit TOTP code at
+ * mint time — never a static password. A legacy static `loginPassword` is still
+ * honoured as a fallback so pre-existing configs don't hard-break.
+ *
+ * SECURITY: the credential (the derived code) is in the request URL, and the
+ * secret must never appear anywhere. We NEVER log the URL — the shared
+ * `n4Request` helper only logs the caller-supplied `label`, so we always pass an
+ * opaque label and never the URL, and errors below never echo it. Only the
+ * short-lived derived code ever reaches the URL; the seed does not.
+ */
+
+type CachedToken = { token: string; expiresAt: number }
+
+const tokenCache = new Map<string, CachedToken>()
+
+export class GctAuthError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'GctAuthError'
+  }
+}
+
+type GctCredentials = { companyCode: string; loginName: string; totpSecret: string; legacyPassword: string }
+
+function credentials(config: ResolvedTerminalConfig): GctCredentials {
+  const auth = (config.authConfig ?? {}) as Record<string, unknown>
+  const companyCode = String(auth.companyCode ?? '')
+  const loginName = String(auth.loginName ?? '')
+  const totpSecret = String(auth.totpSecret ?? '')
+  // Legacy fallback: pre-TOTP configs stored a static `loginPassword`.
+  const legacyPassword = String(auth.loginPassword ?? '')
+  if (!companyCode || !loginName || (!totpSecret && !legacyPassword)) {
+    throw new GctAuthError(
+      `GCT config ${config.terminalCode} is missing companyCode/loginName/totpSecret in auth_config`,
+    )
+  }
+  return { companyCode, loginName, totpSecret, legacyPassword }
+}
+
+/**
+ * The value GCT expects in the password path segment: the current TOTP code
+ * derived from the authenticator secret, or a legacy static password when no
+ * secret is configured.
+ */
+function loginCode(creds: GctCredentials): string {
+  return creds.totpSecret ? generateTotp(creds.totpSecret) : creds.legacyPassword
+}
+
+function cacheKey(config: ResolvedTerminalConfig, creds: GctCredentials): string {
+  // Keyed by principal, NOT org/tenant: identical credentials mint the same
+  // token, so sharing one cache entry is correct. Persisted rows stay
+  // org-scoped independently of this cache.
+  return `${config.terminalCode}:${creds.companyCode}:${creds.loginName}`
+}
+
+function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/$/, '')}/${path.replace(/^\//, '')}`
+}
+
+/** Default GCT auth path; a config may override via `endpoints.auth`. */
+const DEFAULT_AUTH_PATH = '/gctapi/Auth'
+
+/** Default GCT token-refresh (keep-alive) path; override via `endpoints.refresh`. */
+const DEFAULT_REFRESH_PATH = '/gctapi/ping'
+
+function authUrl(config: ResolvedTerminalConfig, creds: GctCredentials, code: string): string {
+  const authPath =
+    (config.endpoints as { auth?: string } | undefined)?.auth?.trim() || DEFAULT_AUTH_PATH
+  const segments = [creds.companyCode, creds.loginName, code]
+    .map((s) => encodeURIComponent(s))
+    .join('/')
+  return joinUrl(config.baseUrl, `${authPath}/${segments}`)
+}
+
+function refreshUrl(config: ResolvedTerminalConfig): string {
+  const refreshPath =
+    (config.endpoints as { refresh?: string } | undefined)?.refresh?.trim() || DEFAULT_REFRESH_PATH
+  return joinUrl(config.baseUrl, refreshPath)
+}
+
+/** Parse GCT's ISO `expires` into epoch ms; null when unparseable. */
+function parseExpires(value: string | undefined): number | null {
+  if (!value) return null
+  const ms = Date.parse(value)
+  return Number.isNaN(ms) ? null : ms
+}
+
+/** Fall back to a conservative 15-minute TTL when `expires` is missing/bad. */
+function tokenTtl(parsed: GctToken, now: number): number {
+  return parseExpires(parsed.expires) ?? now + 15 * 60 * 1000
+}
+
+/**
+ * Full (re-)authentication: derive a fresh authenticator code (it rotates every
+ * 30s) and mint a new token from the path-GET Auth endpoint. Caches and returns
+ * the raw token. This spends one 2FA code, so it is the fallback path — callers
+ * try {@link refreshGctToken} first when they still hold a token.
+ */
+async function mintGctToken(
+  config: ResolvedTerminalConfig,
+  creds: GctCredentials,
+  key: string,
+  now: number,
+): Promise<string> {
+  const { status, ok, text } = await n4Request(
+    authUrl(config, creds, loginCode(creds)),
+    { method: 'GET', headers: { Accept: 'application/json' } },
+    { proxyUrl: config.proxyUrl, label: `${config.terminalCode} auth` },
+  )
+
+  if (!ok) {
+    // Do not include the URL (it carries the derived auth code); status only.
+    throw new GctAuthError(`GCT token request failed (${status}) for ${config.terminalCode}`)
+  }
+
+  let parsed: GctToken
+  try {
+    parsed = JSON.parse(text) as GctToken
+  } catch {
+    throw new GctAuthError(`GCT token response was not JSON for ${config.terminalCode}`)
+  }
+  if (!parsed.token) {
+    throw new GctAuthError(`No token in GCT auth response for ${config.terminalCode}`)
+  }
+
+  const entry: CachedToken = { token: parsed.token, expiresAt: tokenTtl(parsed, now) }
+  tokenCache.set(key, entry)
+  return entry.token
+}
+
+/**
+ * Extend the current token via GCT's keep-alive endpoint
+ * (`GET /gctapi/ping`, current token replayed in the `Authorization` header).
+ * Returns the refreshed cache entry on success, or `null` on ANY failure —
+ * non-2xx, non-JSON, no token in the body, or a network error — so the caller
+ * falls back to a full re-authentication. Never throws (no 2FA code is spent).
+ */
+async function refreshGctToken(
+  config: ResolvedTerminalConfig,
+  token: string,
+  now: number,
+): Promise<CachedToken | null> {
+  let res
+  try {
+    res = await n4Request(
+      refreshUrl(config),
+      { method: 'GET', headers: { Accept: 'application/json', Authorization: token } },
+      { proxyUrl: config.proxyUrl, label: `${config.terminalCode} refresh` },
+    )
+  } catch {
+    // Transient network failure exhausted its retries → re-authenticate.
+    return null
+  }
+  if (!res.ok) return null
+  let parsed: GctToken
+  try {
+    parsed = JSON.parse(res.text) as GctToken
+  } catch {
+    return null
+  }
+  if (!parsed.token) return null
+  return { token: parsed.token, expiresAt: tokenTtl(parsed, now) }
+}
+
+/**
+ * Acquire (and cache) a GCT token for the `Authorization` header. A cached token
+ * is reused until 30s before `expires`. Once it lapses, we first try to REFRESH
+ * it via the keep-alive endpoint (cheap — no 2FA code); only if that fails do we
+ * fully RE-AUTHENTICATE by minting a new token with a fresh authenticator code.
+ */
+export async function acquireGctToken(config: ResolvedTerminalConfig): Promise<string> {
+  const creds = credentials(config)
+  const key = cacheKey(config, creds)
+  const now = Date.now()
+  const cached = tokenCache.get(key)
+  if (cached && cached.expiresAt > now + 30_000) return cached.token
+
+  // (Near-)expired but a token is still in hand: try the keep-alive refresh
+  // before spending a fresh 2FA code. Any refresh failure → full re-auth.
+  if (cached) {
+    const refreshed = await refreshGctToken(config, cached.token, now)
+    if (refreshed) {
+      tokenCache.set(key, refreshed)
+      return refreshed.token
+    }
+  }
+
+  return mintGctToken(config, creds, key, now)
+}
+
+/** Clear the cached token for a terminal (used after a 401). */
+export function invalidateGctToken(config: ResolvedTerminalConfig): void {
+  try {
+    tokenCache.delete(cacheKey(config, credentials(config)))
+  } catch {
+    // Missing creds → nothing cached; ignore.
+  }
+}

package/src/modules/terminal_tracking/lib/adapters/gct/gct-semantics.ts

@@ -0,0 +1,136 @@
+import type { GctContainer } from './types'
+import { DEFAULT_TERMINAL_TIMEZONE, zonedNaiveToUtc } from '../zoned-time'
+import type { TerminalFetchedEvent, ResolvedTerminalConfig } from '../../terminal-adapter'
+import type { TerminalEventType, TerminalEventClassifierCode } from '../../../data/entities'
+
+/**
+ * GCT returns a container *state snapshot*, not a timestamped milestone stream.
+ * We emit only the two milestones GCT actually timestamps — grounding (gate-in)
+ * and pickup (gate-out/departed) — rather than synthesizing discharge/load from
+ * a status code we cannot timestamp. The `eventCode`s (`GTIN`/`DEPA`) are the
+ * same the service maps to `equipment.gate_in` / `transport.departed`, so no
+ * adapter-specific wiring is needed downstream.
+ */
+
+type MilestoneSpec = {
+  eventType: TerminalEventType
+  eventCode: string
+  classifier: TerminalEventClassifierCode
+}
+
+const GATE_IN: MilestoneSpec = { eventType: 'EQUIPMENT', eventCode: 'GTIN', classifier: 'ACT' }
+const DEPARTED: MilestoneSpec = { eventType: 'TRANSPORT', eventCode: 'DEPA', classifier: 'ACT' }
+
+/** The container's direction of travel, inferred from the GCT status prefix. */
+export type GctCargoDirection = 'import' | 'export'
+
+/**
+ * Map `CntrStatus` (XF/EM/XM/IF/XI) to a direction: `X*` = export, `I*` = import.
+ * `EM` (empty, no purpose) and any unknown value yield null. Kept deliberately
+ * lenient — the vendor docs contradict on `IF` (full vs empty) and list an
+ * undocumented `XI`, but Phase 1 does not branch on the full/empty nuance.
+ */
+export function directionFromStatus(status: string | null | undefined): GctCargoDirection | null {
+  const s = (status ?? '').trim().toUpperCase()
+  if (!s) return null
+  if (s.startsWith('X')) return 'export'
+  if (s.startsWith('I')) return 'import'
+  return null
+}
+
+/**
+ * Parse a GCT datetime string. GCT is inconsistent — some fields are ISO-8601
+ * with an explicit offset, others look like N4's "yyyy-mm-dd hh:mm"
+ * (terminal-local, no offset). A field that carries its own timezone is parsed
+ * as-is; a naive one is interpreted in the terminal's timezone (Europe/Warsaw
+ * by default). Returns null when unparseable or empty.
+ */
+export function parseGctDateTime(
+  value: string | null | undefined,
+  timeZone: string = DEFAULT_TERMINAL_TIMEZONE,
+): Date | null {
+  if (!value) return null
+  const raw = value.trim()
+  if (!raw) return null
+  // An explicit timezone (`Z` or `±hh:mm`) is authoritative — parse directly.
+  if (/[zZ]$|[+-]\d{2}:?\d{2}$/.test(raw)) {
+    const ms = Date.parse(raw.replace(' ', 'T'))
+    return Number.isNaN(ms) ? null : new Date(ms)
+  }
+  // Otherwise it is terminal-local-without-offset: interpret it in `timeZone`.
+  const m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/.exec(raw)
+  if (!m) return null
+  const [, yyyy, mm, dd, hh, mi, ss] = m
+  return zonedNaiveToUtc(+yyyy, +mm, +dd, +hh, +mi, ss ? +ss : 0, timeZone)
+}
+
+function buildSourceEventId(terminalCode: string, ufvGkey: string, eventCode: string): string {
+  return `${terminalCode}:${ufvGkey}:${eventCode}`
+}
+
+function baseEvent(
+  container: GctContainer,
+  config: ResolvedTerminalConfig,
+  ufvGkey: string,
+  spec: MilestoneSpec,
+  eventDateTime: Date,
+): TerminalFetchedEvent {
+  const seals = (container.SealList ?? [])
+    .filter((n): n is string => typeof n === 'string' && n.trim() !== '')
+    .map((number) => ({ number, source: config.terminalCode }))
+  const holds = (container.HoldCodesList ?? []).filter(
+    (c): c is string => typeof c === 'string' && c.trim() !== '',
+  )
+  const direction = directionFromStatus(container.CntrStatus)
+
+  return {
+    source: 'terminal',
+    sourceEventId: buildSourceEventId(config.terminalCode, ufvGkey, spec.eventCode),
+    eventType: spec.eventType,
+    eventCode: spec.eventCode,
+    eventClassifierCode: spec.classifier,
+    eventDateTime,
+    containerNumber: container.CntrID,
+    ufvGkey,
+    transitState: container.CntrStatus ?? null,
+    visitState: null,
+    facilityCode: config.facilityCode ?? null,
+    facilityCodeListProvider: config.facilityCodeListProvider ?? null,
+    unlocode: config.unlocode ?? null,
+    visitRefIn: null,
+    visitRefOut: null,
+    // Vessel name/voyage are metadata only — GCT has no vessel-visit endpoint, so
+    // no schedule (ETA/ATA) enrichment is possible.
+    vesselName: container.VesselName ?? null,
+    voyageNumber: container.GCTVoyage ?? container.OwnerVoyage ?? null,
+    modeOfTransport: 'VESSEL',
+    seals: seals.length ? seals : null,
+    vgmWeightKg: typeof container.VGMWeight === 'number' ? container.VGMWeight : null,
+    impediments: holds.length ? holds : null,
+    loadedAt: null,
+    // Preserve the full snapshot plus a normalized direction for downstream use.
+    rawData: { ...container, Category: direction ?? null },
+  }
+}
+
+/**
+ * Turn one GCT container snapshot into zero, one, or two normalized events:
+ * a gate-in when `GroundingDateTime` is set, and a departed when
+ * `PickupDateTime` is set. A snapshot with neither timestamp yields no events
+ * (nothing has provably happened yet).
+ */
+export function mapContainerToEvents(
+  container: GctContainer,
+  config: ResolvedTerminalConfig,
+): TerminalFetchedEvent[] {
+  if (!container.CntrID) return []
+  const ufvGkey = (container.VisitNo && container.VisitNo.trim()) || container.CntrID
+
+  const events: TerminalFetchedEvent[] = []
+  const grounded = parseGctDateTime(container.GroundingDateTime)
+  if (grounded) events.push(baseEvent(container, config, ufvGkey, GATE_IN, grounded))
+  const pickedUp = parseGctDateTime(container.PickupDateTime)
+  if (pickedUp) events.push(baseEvent(container, config, ufvGkey, DEPARTED, pickedUp))
+
+  return events
+}

package/src/modules/terminal_tracking/lib/adapters/gct/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Response shapes for the GCT (Gdynia Container Terminal) API. GCT is a bespoke
+ * FastAPI JSON service (paths under `/gctapi/*`) — unrelated to Navis N4. Only
+ * the fields Phase 1 (read-only tracking) consumes are typed here; the full
+ * `Container` payload is preserved verbatim into `rawData`.
+ *
+ * Source: GCT DEV API OpenAPI 1.1.0 + Karta_kontenera_API.pdf.
+ */
+
+/** `GET /gctapi/Auth/{company}/{login}/{password}` → token envelope. */
+export type GctToken = {
+  token: string
+  token_type: string
+  /** ISO-8601 instant the token is valid until. */
+  expires: string
+}
+
+/**
+ * One container as returned by `POST /gctapi/GetContainerDetails`. Every field
+ * is optional in practice; GCT omits what it has no value for. `CntrID` is the
+ * only guaranteed member.
+ */
+export type GctContainer = {
+  CntrID: string
+  /** Per-visit terminal key — the dedup anchor (→ `ufvGkey`). */
+  VisitNo?: string | null
+  /** Container status: XF/EM/XM/IF/XI (export/import, full/empty). */
+  CntrStatus?: string | null
+  CntrSize?: string | null
+  CntrType?: string | null
+  /** Grounding (gate-in) instant — the container's arrival on the terminal. */
+  GroundingDateTime?: string | null
+  /** Pickup (gate-out) instant — the container left the terminal. */
+  PickupDateTime?: string | null
+  /** Impediment ("stopki") codes currently on the container. */
+  HoldCodesList?: string[] | null
+  /** Seals verified at GCT. */
+  SealList?: string[] | null
+  VGMWeight?: number | null
+  VesselName?: string | null
+  /** Voyage per GCT numbering. */
+  GCTVoyage?: string | null
+  /** Voyage per the line's own numbering. */
+  OwnerVoyage?: string | null
+  DischargePort?: string | null
+  FinalDestinationPort?: string | null
+  LoadingPort?: string | null
+  OriginPort?: string | null
+  Location?: string | null
+  // Remaining fields are preserved via the index signature into rawData.
+  [key: string]: unknown
+}
+
+/** `POST /gctapi/GetContainerDetails` response body. */
+export type GctContainerDetailsResponse = {
+  Total?: number
+  Containers?: GctContainer[]
+}

package/src/modules/terminal_tracking/lib/adapters/index.ts

@@ -0,0 +1,16 @@
+import type { TerminalRegistry } from '../../services/terminalRegistry'
+import { N4TerminalAdapter } from './n4/adapter'
+import { GctTerminalAdapter } from './gct/adapter'
+import { BctTerminalAdapter } from './bct/adapter'
+
+/**
+ * Register all built-in terminal adapters. Adapters are keyed by `adapterType`;
+ * a single adapter serves every terminal of that type (N4 → Baltic Hub etc.,
+ * GCT → Gdynia Container Terminal, BCT → Bałtycki Terminal Kontenerowy via
+ * INCOS), which are configured as `TerminalConfig` rows, not hardcoded here.
+ */
+export function registerAllAdapters(registry: TerminalRegistry): void {
+  registry.register(new N4TerminalAdapter())
+  registry.register(new GctTerminalAdapter())
+  registry.register(new BctTerminalAdapter())
+}

package/src/modules/terminal_tracking/lib/adapters/n4/__tests__/adapter-proxy.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+
+// The adapter's fetches run through `n4Request`, which drives undici's `fetch`
+// (same instance as the dispatcher). Mock the undici module, keeping the real
+// ProxyAgent/Agent so `dispatcher` is built exactly as in production.
+const { fetchMock } = vi.hoisted(() => ({ fetchMock: vi.fn() }))
+vi.mock('undici', async (orig) => {
+  const actual = await orig<typeof import('undici')>()
+  return { ...actual, fetch: fetchMock }
+})
+
+import { N4TerminalAdapter } from '../adapter'
+import type { ResolvedTerminalConfig } from '../../../terminal-adapter'
+
+let counter = 0
+function cfg(proxyUrl: string | null): ResolvedTerminalConfig {
+  // Unique terminalCode per config to bypass the process-level token cache.
+  return {
+    terminalCode: `proxytest-${counter++}`,
+    adapterType: 'n4',
+    displayName: 'x',
+    baseUrl: 'https://api2.baltichub.com/V1/',
+    proxyUrl,
+    endpoints: { unit: '/unit', vessel: '/VESSEL' },
+    authType: 'oauth2_password',
+    tokenUrl: 'https://token.example/token',
+    clientId: 'c',
+    authConfig: { username: 'u', password: 'p' },
+    rateLimitRequests: 200,
+    rateLimitWindowSeconds: 60,
+  }
+}
+
+function stubFetch() {
+  fetchMock.mockImplementation(async (_url: string | URL, init?: any) => {
+    if (init?.method === 'POST') {
+      return new Response(JSON.stringify({ access_token: 'tok', expires_in: 3600 }), { status: 200 })
+    }
+    return new Response(
+      JSON.stringify({ 'query-response': { 'data-table': { columns: { column: [] }, rows: null } } }),
+      { status: 200 },
+    )
+  })
+  return fetchMock
+}
+
+afterEach(() => fetchMock.mockReset())
+
+describe('N4 adapter proxy dispatcher', () => {
+  it('attaches a dispatcher to the API + token fetches when proxyUrl is set', async () => {
+    stubFetch()
+    await new N4TerminalAdapter().fetchVesselVisit({ visitRef: '26AAA1', config: cfg('http://127.0.0.1:8888') })
+
+    const vesselCall = fetchMock.mock.calls.find((c) => String(c[0]).includes('/VESSEL'))
+    const tokenCall = fetchMock.mock.calls.find((c) => (c[1] as any)?.method === 'POST')
+    expect(vesselCall?.[1]?.dispatcher).toBeDefined()
+    expect(tokenCall?.[1]?.dispatcher).toBeDefined()
+  })
+
+  it('uses no dispatcher when proxyUrl is null (direct)', async () => {
+    stubFetch()
+    await new N4TerminalAdapter().fetchVesselVisit({ visitRef: '26BBB2', config: cfg(null) })
+
+    const vesselCall = fetchMock.mock.calls.find((c) => String(c[0]).includes('/VESSEL'))
+    const tokenCall = fetchMock.mock.calls.find((c) => (c[1] as any)?.method === 'POST')
+    expect(vesselCall?.[1]?.dispatcher).toBeUndefined()
+    expect(tokenCall?.[1]?.dispatcher).toBeUndefined()
+  })
+})

package/src/modules/terminal_tracking/lib/adapters/n4/__tests__/data-table.test.ts

@@ -0,0 +1,179 @@
+import { parseUnitDataTable, type N4DataTableResponse } from '../parsers/data-table'
+
+const COLUMNS = [
+  'Unit Nbr', 'T-State', 'V-State', 'Category', 'Line Op', 'Type ISO', 'Frght Kind',
+  'I/B Actual Visit', 'O/B Actual Visit', 'Time In', 'Time Out', 'Unit Impediments',
+  'CEN Number', 'Cmdy Weight', 'VGM Weight', 'Cargo Wt (kg)', 'Tare Wt', 'Weight (kg)',
+  'Seal Nbr1', 'Seal Nbr2', 'Seal Nbr3', 'Seal Nbr4', 'DSK Number', 'Loaded',
+]
+
+// Real Baltic Hub /unit response shape for container GCXU5598460 (two UFV legs).
+const REAL_RESPONSE: N4DataTableResponse = {
+  'query-response': {
+    'data-table': {
+      '@count': '2',
+      columns: { column: COLUMNS },
+      rows: {
+        row: [
+          {
+            '@primary-key': '11412344487',
+            field: ['GCXU5598460', 'Inbound', 'Active', 'Export', 'MAE', '45G1', 'FCL',
+              'GEN_TRUCK', '26WIKI624', null, null,
+              '!TECHNICAL_FULL_CONTAINER,!CUSTOMS EXPORT PERMISSION,!MISSING_AGENT_PERMISSION',
+              null, '24600', '28300.0', '24600.0', '3700.0', '28300.0',
+              null, null, null, null, null, null],
+          },
+          {
+            '@primary-key': '11341499051',
+            field: ['GCXU5598460', 'Departed', 'Departed', 'Import', 'MAE', '45G1', 'FCL',
+              '26GIRO622', 'RST62379', '2026-05-27 23:41', '2026-06-03 01:58',
+              '!TECHNICAL_FULL_CONTAINER,!MISSING_AGENT_PERMISSION', '26PL32208D005FRKR0',
+              '6360', '10060.0', '6360.0', '3700.0', '10060.0',
+              'CN7842852', null, null, null, '26GIRO622 2026-05-26 19:39', '2026-06-03 01:47'],
+          },
+        ],
+      },
+    },
+  },
+}
+
+describe('parseUnitDataTable', () => {
+  it('parses both UFV legs, mapping @primary-key to ufvGkey and fields by header name', () => {
+    const rows = parseUnitDataTable(REAL_RESPONSE)
+    expect(rows).toHaveLength(2)
+
+    const [exp, imp] = rows
+    // @primary-key -> ufvGkey (the N4 Ufv_Gkey)
+    expect(exp.ufvGkey).toBe('11412344487')
+    expect(imp.ufvGkey).toBe('11341499051')
+
+    // Positional field[] mapped by column header
+    expect(exp.unitNbr).toBe('GCXU5598460')
+    expect(exp.tState).toBe('Inbound')
+    expect(exp.category).toBe('Export')
+    expect(exp.ibActualVisit).toBe('GEN_TRUCK')
+    expect(exp.obActualVisit).toBe('26WIKI624')
+    expect(exp.vgmWeight).toBe(28300)
+    expect(exp.cargoWtKg).toBe(24600)
+
+    expect(imp.tState).toBe('Departed')
+    expect(imp.timeIn).toBe('2026-05-27 23:41')
+    expect(imp.timeOut).toBe('2026-06-03 01:58')
+    expect(imp.loaded).toBe('2026-06-03 01:47')
+    expect(imp.dskNumber).toBe('26GIRO622 2026-05-26 19:39')
+  })
+
+  it('splits impediments and collects non-empty seals', () => {
+    const [exp, imp] = parseUnitDataTable(REAL_RESPONSE)
+    expect(exp.impediments).toEqual([
+      '!TECHNICAL_FULL_CONTAINER', '!CUSTOMS EXPORT PERMISSION', '!MISSING_AGENT_PERMISSION',
+    ])
+    expect(exp.seals).toEqual([]) // all four seal columns null
+    expect(imp.seals).toEqual(['CN7842852']) // only Seal Nbr1 populated
+  })
+
+  it('preserves the full raw row (null for empty columns)', () => {
+    const [exp] = parseUnitDataTable(REAL_RESPONSE)
+    expect(exp.raw['Category']).toBe('Export')
+    expect(exp.raw['Time In']).toBeNull()
+    expect(Object.keys(exp.raw)).toHaveLength(COLUMNS.length)
+  })
+
+  it('tolerates XML->JSON single-element collapsing (row/column as objects, not arrays)', () => {
+    const single: N4DataTableResponse = {
+      'query-response': {
+        'data-table': {
+          '@count': '1',
+          columns: { column: COLUMNS },
+          rows: {
+            row: {
+              '@primary-key': '999',
+              field: ['MSKU1', 'Yard', 'Active', 'Import', 'MSC', '22G1', 'FCL',
+                'V1', null, '2026-01-01 10:00', null, null, null, null, null, null, null, null,
+                null, null, null, null, null, null],
+            },
+          },
+        },
+      },
+    }
+    const rows = parseUnitDataTable(single)
+    expect(rows).toHaveLength(1)
+    expect(rows[0].ufvGkey).toBe('999')
+    expect(rows[0].unitNbr).toBe('MSKU1')
+    expect(rows[0].tState).toBe('Yard')
+  })
+
+  it('reports all-null stops for a pre-update payload lacking the STOP columns', () => {
+    const [exp, imp] = parseUnitDataTable(REAL_RESPONSE)
+    expect(exp.stops).toEqual({ vsl: null, road: null, rail: null })
+    expect(imp.stops).toEqual({ vsl: null, road: null, rail: null })
+  })
+
+  it('parses the new Stop-Vsl / Stop-Road / Stop-Rail columns when present', () => {
+    const withStops: N4DataTableResponse = {
+      'query-response': {
+        'data-table': {
+          '@count': '1',
+          columns: { column: [...COLUMNS, 'Stop-Vsl', 'Stop-Road', 'Stop-Rail'] },
+          rows: {
+            row: {
+              '@primary-key': '555',
+              field: ['MSKU2', 'Yard', 'Active', 'Import', 'MSC', '22G1', 'FCL',
+                'V1', null, '2026-01-01 10:00', null, null, null, null, null, null, null, null,
+                null, null, null, null, null, null,
+                'N', 'Y', null],
+            },
+          },
+        },
+      },
+    }
+    const [row] = parseUnitDataTable(withStops)
+    expect(row.stops).toEqual({ vsl: false, road: true, rail: false })
+  })
+
+  it('parses a real post-update Baltic Hub payload (27 columns, Stop-* = "false")', () => {
+    // Verbatim shape from a real /unit response (container ECMU7554418, 2026-07):
+    // the STOP columns arrive in Vsl, Rail, Road order with string "false" values,
+    // and empties report Frght Kind "Empty" (not "MTY").
+    const REAL_WITH_STOPS: N4DataTableResponse = {
+      'query-response': {
+        'data-table': {
+          '@count': '2',
+          columns: {
+            column: [...COLUMNS, 'Stop-Vsl', 'Stop-Rail', 'Stop-Road'],
+          },
+          rows: {
+            row: [
+              {
+                '@primary-key': '11643960646',
+                field: ['ECMU7554418', 'Departed', 'Departed', 'Export', 'CMA', '45G1', 'Empty',
+                  'BC1455XA', '26SPAI012', '2026-07-06 09:53', '2026-07-12 04:30', null, null, null,
+                  null, '0.0', '4000.0', '4000.0', null, null, null, null, null, '2026-07-09 21:21',
+                  'false', 'false', 'false'],
+              },
+              {
+                '@primary-key': '11483997354',
+                field: ['ECMU7554418', 'Departed', 'Departed', 'Import', 'CMA', '45G1', 'FCL',
+                  '26CCJA1FL1MA', 'BC1455XA', '2026-06-22 17:15', '2026-06-30 14:49',
+                  '!TECHNICAL_FULL_CONTAINER,!MISSING_AGENT_PERMISSION', '26PL322080NSJAGEK7',
+                  '18320', '22020.0', '18020.0', '4000.0', '22020.0', 'M7663322', null, null, null,
+                  '26CCJA1FL1MA 2026-06-22 05:55', '2026-06-30 14:40', 'false', 'false', 'false'],
+              },
+            ],
+          },
+        },
+      },
+    }
+    const [mty, fcl] = parseUnitDataTable(REAL_WITH_STOPS)
+    expect(mty.raw['Frght Kind']).toBe('Empty')
+    expect(mty.stops).toEqual({ vsl: false, road: false, rail: false })
+    expect(fcl.stops).toEqual({ vsl: false, road: false, rail: false })
+    // Header order in the payload is Vsl, Rail, Road — name-indexed parsing is order-agnostic.
+    expect(mty.raw['Stop-Road']).toBe('false')
+  })
+
+  it('returns [] for an empty (rows: null) or malformed envelope', () => {
+    expect(parseUnitDataTable({ 'query-response': { 'data-table': { '@count': '0', columns: { column: COLUMNS }, rows: null } } })).toEqual([])
+    expect(parseUnitDataTable({})).toEqual([])
+  })
+})