@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/lib/adapters/n4/__tests__/http.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+
+// `n4Request` drives requests with undici's `fetch` (same instance as the
+// dispatcher), so the mock targets the undici module, not the global fetch.
+const { fetchMock } = vi.hoisted(() => ({ fetchMock: vi.fn() }))
+vi.mock('undici', async (orig) => {
+  const actual = await orig<typeof import('undici')>()
+  return { ...actual, fetch: fetchMock }
+})
+
+import { n4Request, isTransientNetworkError } from '../http'
+
+function socketClose(): TypeError {
+  // Mirrors undici's mid-flight peer close: `TypeError: terminated` with an
+  // UND_ERR_SOCKET cause — the exact error that crashed the queue worker.
+  return Object.assign(new TypeError('terminated'), {
+    cause: Object.assign(new Error('other side closed'), { code: 'UND_ERR_SOCKET' }),
+  })
+}
+
+afterEach(() => fetchMock.mockReset())
+
+describe('isTransientNetworkError', () => {
+  it('treats undici socket close / terminated as transient', () => {
+    expect(isTransientNetworkError(socketClose())).toBe(true)
+    expect(isTransientNetworkError(Object.assign(new Error('x'), { code: 'ECONNRESET' }))).toBe(true)
+  })
+
+  it('does not treat a generic error or an HTTP status as transient', () => {
+    expect(isTransientNetworkError(new TypeError('bad argument'))).toBe(false)
+    expect(isTransientNetworkError(new Error('Unit request failed (403)'))).toBe(false)
+  })
+})
+
+describe('n4Request', () => {
+  it('returns status + fully-read body on success', async () => {
+    fetchMock.mockResolvedValue(new Response('{"ok":true}', { status: 200 }))
+
+    const res = await n4Request('https://t/unit', { method: 'GET' }, { retries: 0 })
+    expect(res).toEqual({ status: 200, ok: true, text: '{"ok":true}' })
+  })
+
+  it('ALWAYS drains the body, even on a non-ok status (no dangling stream)', async () => {
+    // The crash root cause: a non-ok response whose body was never read left a
+    // stream undrained on a keep-alive socket. Assert the body is consumed.
+    const resp = new Response('403 forbidden', { status: 403 })
+    fetchMock.mockResolvedValue(resp)
+
+    const out = await n4Request('https://t/unit', { method: 'GET' }, { retries: 0 })
+    expect(out).toEqual({ status: 403, ok: false, text: '403 forbidden' })
+    expect(resp.bodyUsed).toBe(true)
+  })
+
+  it('retries a transient socket close, then succeeds', async () => {
+    fetchMock
+      .mockRejectedValueOnce(socketClose())
+      .mockResolvedValueOnce(new Response('{"ok":true}', { status: 200 }))
+
+    const res = await n4Request('https://t/unit', { method: 'GET' }, { retries: 2, retryBackoffMs: 0 })
+    expect(res.ok).toBe(true)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('gives up after exhausting retries and rethrows the transient error', async () => {
+    fetchMock.mockRejectedValue(socketClose())
+
+    await expect(
+      n4Request('https://t/unit', { method: 'GET' }, { retries: 2, retryBackoffMs: 0 }),
+    ).rejects.toThrow(/terminated/)
+    expect(fetchMock).toHaveBeenCalledTimes(3) // 1 initial + 2 retries
+  })
+
+  it('does NOT retry a non-transient error', async () => {
+    fetchMock.mockRejectedValue(new TypeError('bad argument'))
+
+    await expect(
+      n4Request('https://t/unit', { method: 'GET' }, { retries: 3, retryBackoffMs: 0 }),
+    ).rejects.toThrow(/bad argument/)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('does NOT retry an HTTP error status (a real answer, not a drop)', async () => {
+    fetchMock.mockResolvedValue(new Response('nope', { status: 500 }))
+
+    const res = await n4Request('https://t/unit', { method: 'GET' }, { retries: 3, retryBackoffMs: 0 })
+    expect(res.status).toBe(500)
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('passes a proxy dispatcher and an abort signal to fetch', async () => {
+    fetchMock.mockResolvedValue(new Response('{}', { status: 200 }))
+
+    await n4Request('https://t/unit', { method: 'GET' }, { proxyUrl: 'http://127.0.0.1:8888', retries: 0 })
+    const init = fetchMock.mock.calls[0]?.[1] as { dispatcher?: unknown; signal?: unknown }
+    expect(init?.dispatcher).toBeDefined()
+    expect(init?.signal).toBeInstanceOf(AbortSignal)
+  })
+})

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

@@ -0,0 +1,140 @@
+import { mapRowToEvent, buildSourceEventId, parseCargoCategory, parseN4DateTime, pickVesselVisit } from '../n4-semantics'
+import type { N4UnitRow } from '../types'
+import type { ResolvedTerminalConfig } from '../../../terminal-adapter'
+
+const config: ResolvedTerminalConfig = {
+  terminalCode: 'bct',
+  adapterType: 'n4',
+  displayName: 'Baltic Hub',
+  baseUrl: 'https://api2.baltichub.com/V1/',
+  endpoints: { unit: '/unit' },
+  authType: 'oauth2_password',
+  rateLimitRequests: 200,
+  rateLimitWindowSeconds: 60,
+  unlocode: 'PLGDN',
+  facilityCode: 'GDNBCT',
+  facilityCodeListProvider: 'SMDG',
+}
+
+function row(partial: Partial<N4UnitRow>): N4UnitRow {
+  return { ufvGkey: '1', unitNbr: 'GCXU5598460', raw: {}, ...partial }
+}
+
+describe('mapRowToEvent', () => {
+  it('maps an inbound export leg to an EQUIPMENT/GTIN actual event', () => {
+    const ev = mapRowToEvent(
+      row({ ufvGkey: '11412344487', tState: 'Inbound', ibActualVisit: 'GEN_TRUCK', obActualVisit: '26WIKI624', vgmWeight: 28300 }),
+      config,
+    )
+    expect(ev).not.toBeNull()
+    expect(ev!.source).toBe('terminal')
+    expect(ev!.eventType).toBe('EQUIPMENT')
+    expect(ev!.eventCode).toBe('GTIN')
+    expect(ev!.eventClassifierCode).toBe('ACT')
+    expect(ev!.transitState).toBe('S20_INBOUND')
+    expect(ev!.sourceEventId).toBe('bct:11412344487:GTIN')
+    expect(ev!.containerNumber).toBe('GCXU5598460')
+    expect(ev!.facilityCode).toBe('GDNBCT')
+    expect(ev!.facilityCodeListProvider).toBe('SMDG')
+    expect(ev!.unlocode).toBe('PLGDN')
+    expect(ev!.vgmWeightKg).toBe(28300)
+  })
+
+  it('maps a departed leg to a TRANSPORT/DEPA event dated from Time Out', () => {
+    const ev = mapRowToEvent(
+      row({ ufvGkey: '11341499051', tState: 'Departed', timeIn: '2026-05-27 23:41', timeOut: '2026-06-03 01:58', loaded: '2026-06-03 01:47' }),
+      config,
+    )
+    expect(ev!.eventType).toBe('TRANSPORT')
+    expect(ev!.eventCode).toBe('DEPA')
+    expect(ev!.transitState).toBe('S70_DEPARTED')
+    expect(ev!.sourceEventId).toBe('bct:11341499051:DEPA')
+    // Terminal-local (Europe/Warsaw, CEST +02:00 in June) → UTC.
+    expect(ev!.eventDateTime.toISOString()).toBe('2026-06-02T23:58:00.000Z')
+    // loadedAt is parsed from `Loaded` even though this row is Departed (not
+    // S60_LOADED) — independent of the event timestamp (which came from Time Out).
+    expect(ev!.loadedAt?.toISOString()).toBe('2026-06-02T23:47:00.000Z')
+  })
+
+  it('leaves loadedAt null when the row has no Loaded value', () => {
+    const ev = mapRowToEvent(row({ tState: 'Inbound', ibActualVisit: 'GEN_TRUCK' }), config)
+    expect(ev!.loadedAt).toBeNull()
+  })
+
+  it('returns null for an unmapped transit state', () => {
+    expect(mapRowToEvent(row({ tState: 'Advised' }), config)).toBeNull()
+    expect(mapRowToEvent(row({ tState: null }), config)).toBeNull()
+  })
+
+  it('infers mode of transport from the visit refs', () => {
+    expect(mapRowToEvent(row({ tState: 'Inbound', ibActualVisit: 'GEN_TRUCK', obActualVisit: null }), config)!.modeOfTransport).toBe('TRUCK')
+    expect(mapRowToEvent(row({ tState: 'Departed', obActualVisit: 'TUX3W31-25_IMP' }), config)!.modeOfTransport).toBe('RAIL')
+    expect(mapRowToEvent(row({ tState: 'Departed', obActualVisit: '25CHAM531' }), config)!.modeOfTransport).toBe('VESSEL')
+  })
+
+  it('produces a stable sourceEventId (idempotent across polls)', () => {
+    const r = row({ ufvGkey: '777', tState: 'Loaded' })
+    const a = mapRowToEvent(r, config)!
+    const b = mapRowToEvent(r, config)!
+    expect(a.sourceEventId).toBe(b.sourceEventId)
+    expect(a.sourceEventId).toBe('bct:777:LOAD')
+  })
+})
+
+describe('buildSourceEventId', () => {
+  it('joins terminalCode, gkey and eventCode', () => {
+    expect(buildSourceEventId('bct', '123', 'GTIN')).toBe('bct:123:GTIN')
+  })
+})
+
+describe('parseCargoCategory', () => {
+  it('normalizes the N4 Category column to a direction', () => {
+    expect(parseCargoCategory({ Category: 'Import' })).toBe('import')
+    expect(parseCargoCategory({ Category: ' export ' })).toBe('export')
+  })
+
+  it('is null for non-directional or missing categories', () => {
+    expect(parseCargoCategory({ Category: 'Storage' })).toBeNull() // empties
+    expect(parseCargoCategory({})).toBeNull()
+    expect(parseCargoCategory(null)).toBeNull()
+  })
+})
+
+describe('pickVesselVisit', () => {
+  it('picks the I/B visit for an import leg', () => {
+    expect(
+      pickVesselVisit({ visitRefIn: '26JAPA038', visitRefOut: 'POS75955', rawData: { Category: 'Import' } }),
+    ).toEqual({ ref: '26JAPA038', dir: 'in' })
+  })
+
+  it('picks the O/B visit for an export leg (vessel on the outbound side)', () => {
+    expect(
+      pickVesselVisit({ visitRefIn: 'GDA56850', visitRefOut: '26OOFX010', rawData: { Category: 'Export' } }),
+    ).toEqual({ ref: '26OOFX010', dir: 'out' })
+  })
+
+  it('returns null for an unknown category or missing rawData', () => {
+    expect(pickVesselVisit({ visitRefIn: '26X', visitRefOut: '26Y', rawData: { Category: 'Storage' } })).toBeNull()
+    expect(pickVesselVisit({ visitRefIn: '26X', visitRefOut: '26Y', rawData: null })).toBeNull()
+  })
+
+  it('returns null when the relevant side is missing', () => {
+    expect(pickVesselVisit({ visitRefIn: null, visitRefOut: '26Y', rawData: { Category: 'Import' } })).toBeNull()
+  })
+})
+
+describe('parseN4DateTime', () => {
+  it('parses "yyyy-mm-dd hh:mm" as terminal-local (Europe/Warsaw) → UTC', () => {
+    // 23:41 CEST (+02:00) on 2026-05-27 is 21:41 UTC.
+    expect(parseN4DateTime('2026-05-27 23:41')!.toISOString()).toBe('2026-05-27T21:41:00.000Z')
+  })
+  it('honours an explicit timezone argument', () => {
+    // Same wall-clock, read as UTC when the terminal's zone is UTC.
+    expect(parseN4DateTime('2026-05-27 23:41', 'UTC')!.toISOString()).toBe('2026-05-27T23:41:00.000Z')
+  })
+  it('returns null for empty / invalid input', () => {
+    expect(parseN4DateTime(null)).toBeNull()
+    expect(parseN4DateTime('')).toBeNull()
+    expect(parseN4DateTime('not a date')).toBeNull()
+  })
+})

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

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest'
+import { proxyDispatcher } from '../proxy'
+
+describe('proxyDispatcher', () => {
+  it('returns undefined when no proxy is configured', () => {
+    expect(proxyDispatcher(undefined)).toBeUndefined()
+    expect(proxyDispatcher(null)).toBeUndefined()
+    expect(proxyDispatcher('')).toBeUndefined()
+  })
+
+  it('memoises one agent per proxy URL', () => {
+    const a = proxyDispatcher('http://127.0.0.1:8888')
+    const b = proxyDispatcher('http://127.0.0.1:8888')
+    expect(a).toBeDefined()
+    expect(a).toBe(b) // same instance reused
+    const c = proxyDispatcher('http://127.0.0.1:9999')
+    expect(c).not.toBe(a)
+  })
+})

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

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest'
+import { parseVesselDataTable } from '../parsers/vessel-data-table'
+import type { N4DataTableResponse } from '../parsers/data-table'
+
+const COLUMNS = [
+  'Visit', 'Vessel Name', 'I/B Vyg', 'O/B Vyg', 'Line', 'Phase',
+  'ETA', 'ETD', 'ATA', 'ATD', 'Begin Receive', 'DryCutoff',
+]
+
+// Real Baltic Hub /VESSEL response for VISIT_REF=26NUBA625 (single row).
+const REAL_RESPONSE: N4DataTableResponse = {
+  'query-response': {
+    'data-table': {
+      '@count': '1',
+      columns: { column: COLUMNS },
+      rows: {
+        row: {
+          '@primary-key': '11000443969',
+          field: [
+            '26NUBA625', 'MAERSK NUBA', '623N', '625S', 'MAE', 'Inbound',
+            '2026-06-14 10:00', '2026-06-15 18:00', null, null,
+            '2026-06-07 10:00', null,
+          ],
+        },
+      },
+    },
+  },
+}
+
+describe('parseVesselDataTable', () => {
+  it('maps the real /VESSEL row by header name', () => {
+    const row = parseVesselDataTable(REAL_RESPONSE)
+    expect(row).not.toBeNull()
+    expect(row).toMatchObject({
+      visitRef: '26NUBA625',
+      vesselName: 'MAERSK NUBA',
+      ibVoyage: '623N',
+      obVoyage: '625S',
+      line: 'MAE',
+      phase: 'Inbound',
+      eta: '2026-06-14 10:00',
+      etd: '2026-06-15 18:00',
+      ata: null,
+      atd: null,
+      beginReceive: '2026-06-07 10:00',
+      dryCutoff: null,
+    })
+  })
+
+  it('preserves the full header->value map in raw', () => {
+    const row = parseVesselDataTable(REAL_RESPONSE)!
+    expect(row.raw['Line']).toBe('MAE')
+    expect(row.raw['Begin Receive']).toBe('2026-06-07 10:00')
+    expect(row.raw['DryCutoff']).toBeNull()
+  })
+
+  it('returns null when there are no rows', () => {
+    const empty: N4DataTableResponse = {
+      'query-response': { 'data-table': { '@count': '0', columns: { column: COLUMNS }, rows: null } },
+    }
+    expect(parseVesselDataTable(empty)).toBeNull()
+  })
+
+  it('returns null on an empty envelope', () => {
+    expect(parseVesselDataTable({} as N4DataTableResponse)).toBeNull()
+  })
+})

package/src/modules/terminal_tracking/lib/adapters/n4/adapter.ts

@@ -0,0 +1,163 @@
+import type {
+  TerminalAdapter,
+  TerminalFetchResult,
+  TerminalFetchedEvent,
+  TerminalAdapterTestResult,
+  ResolvedTerminalConfig,
+  NormalizedVesselVisit,
+} from '../../terminal-adapter'
+import { acquireToken, invalidateToken, TerminalAuthError } from './auth/ropc'
+import { parseUnitDataTable, type N4DataTableResponse } from './parsers/data-table'
+import { parseVesselDataTable } from './parsers/vessel-data-table'
+import { mapRowToEvent, parseN4DateTime } from './n4-semantics'
+import { n4Request } from './http'
+import { terminalLogger } from '../../logger'
+
+function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/$/, '')}/${path.replace(/^\//, '')}`
+}
+
+/** Parse an N4 JSON body, turning a malformed payload into a clear adapter error. */
+function parseN4Json(text: string, terminalCode: string, what: string): N4DataTableResponse {
+  try {
+    return JSON.parse(text) as N4DataTableResponse
+  } catch {
+    throw new Error(`${what} response was not valid JSON for ${terminalCode}`)
+  }
+}
+
+/**
+ * Config-driven adapter for Navis N4 terminals. One instance serves all N4
+ * terminals; per-terminal differences live in the TerminalConfig.
+ */
+export class N4TerminalAdapter implements TerminalAdapter {
+  readonly adapterType = 'n4'
+
+  readonly defaultEndpoints = {
+    unit: '/unit',
+    vessel: '/VESSEL',
+    trainVisits: '/TRAIN_VISITS',
+  }
+
+  private async getUnitMany(
+    containerNumbers: string[],
+    config: ResolvedTerminalConfig,
+    token: string,
+  ): Promise<N4DataTableResponse> {
+    // N4 /unit accepts a comma-separated UNIT_NBR list; encode each part so the
+    // commas stay as the list separator.
+    const joined = containerNumbers.map((c) => encodeURIComponent(c)).join(',')
+    const url = `${joinUrl(config.baseUrl, config.endpoints.unit)}?UNIT_NBR=${joined}`
+    const { status, ok, text } = await n4Request(
+      url,
+      { method: 'GET', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' } },
+      { proxyUrl: config.proxyUrl, label: `${config.terminalCode} /unit` },
+    )
+    if (status === 401) {
+      invalidateToken(config)
+      throw new TerminalAuthError(`Unit request unauthorized (401) for ${config.terminalCode}`)
+    }
+    if (!ok) {
+      throw new Error(`Unit request failed (${status}) for ${config.terminalCode}`)
+    }
+    return parseN4Json(text, config.terminalCode, 'Unit')
+  }
+
+  private async getVessel(
+    visitRef: string,
+    config: ResolvedTerminalConfig,
+    token: string,
+  ): Promise<N4DataTableResponse> {
+    const url = `${joinUrl(config.baseUrl, config.endpoints.vessel as string)}?VISIT_REF=${encodeURIComponent(visitRef)}`
+    const { status, ok, text } = await n4Request(
+      url,
+      { method: 'GET', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' } },
+      { proxyUrl: config.proxyUrl, label: `${config.terminalCode} /VESSEL` },
+    )
+    if (status === 401) {
+      invalidateToken(config)
+      throw new TerminalAuthError(`Vessel request unauthorized (401) for ${config.terminalCode}`)
+    }
+    if (!ok) {
+      throw new Error(`Vessel request failed (${status}) for ${config.terminalCode}`)
+    }
+    return parseN4Json(text, config.terminalCode, 'Vessel')
+  }
+
+  async fetchVesselVisit(input: {
+    visitRef: string
+    config: ResolvedTerminalConfig
+  }): Promise<NormalizedVesselVisit | null> {
+    const { visitRef, config } = input
+    if (!config.endpoints.vessel) return null
+
+    const token = await acquireToken(config)
+    const body = await this.getVessel(visitRef, config, token)
+    const row = parseVesselDataTable(body)
+    if (!row) return null
+
+    return {
+      visitRef: row.visitRef,
+      vesselName: row.vesselName,
+      ibVoyage: row.ibVoyage,
+      obVoyage: row.obVoyage,
+      line: row.line,
+      phase: row.phase,
+      eta: parseN4DateTime(row.eta),
+      etd: parseN4DateTime(row.etd),
+      ata: parseN4DateTime(row.ata),
+      atd: parseN4DateTime(row.atd),
+      beginReceive: parseN4DateTime(row.beginReceive),
+      dryCutoff: parseN4DateTime(row.dryCutoff),
+      rawData: row.raw,
+    }
+  }
+
+  async fetchEvents(input: {
+    containerNumber: string
+    config: ResolvedTerminalConfig
+  }): Promise<TerminalFetchResult> {
+    const { containerNumber, config } = input
+    const { events } = await this.fetchEventsBatch({ containerNumbers: [containerNumber], config })
+    return { events, containerNumber }
+  }
+
+  async fetchEventsBatch(input: {
+    containerNumbers: string[]
+    config: ResolvedTerminalConfig
+  }): Promise<{ events: TerminalFetchedEvent[] }> {
+    const { containerNumbers, config } = input
+    if (containerNumbers.length === 0) return { events: [] }
+
+    const token = await acquireToken(config)
+    const body = await this.getUnitMany(containerNumbers, config, token)
+    const rows = parseUnitDataTable(body)
+
+    const events: TerminalFetchedEvent[] = []
+    for (const row of rows) {
+      const event = mapRowToEvent(row, config)
+      if (event) events.push(event)
+    }
+
+    terminalLogger.debug('fetchEventsBatch', {
+      terminalCode: config.terminalCode,
+      containers: containerNumbers.length,
+      rows: rows.length,
+      events: events.length,
+    })
+
+    return { events }
+  }
+
+  async testConnection(config: ResolvedTerminalConfig): Promise<TerminalAdapterTestResult> {
+    const started = Date.now()
+    try {
+      await acquireToken(config)
+      return { success: true, message: 'Token acquired', latencyMs: Date.now() - started }
+    } catch (err) {
+      const code = err instanceof TerminalAuthError ? err.code : undefined
+      const message = err instanceof Error ? err.message : String(err)
+      return { success: false, message: code ? `${message} (${code})` : message, latencyMs: Date.now() - started }
+    }
+  }
+}

package/src/modules/terminal_tracking/lib/adapters/n4/auth/ropc.ts

@@ -0,0 +1,104 @@
+import type { ResolvedTerminalConfig } from '../../../terminal-adapter'
+import { n4Request } from '../http'
+
+type CachedToken = { token: string; expiresAt: number }
+
+// Process-level token cache, keyed by terminal + principal.
+const tokenCache = new Map<string, CachedToken>()
+
+export class TerminalAuthError extends Error {
+  constructor(
+    message: string,
+    readonly code?: string,
+  ) {
+    super(message)
+    this.name = 'TerminalAuthError'
+  }
+}
+
+function cacheKey(config: ResolvedTerminalConfig): string {
+  const principal =
+    config.authType === 'oauth2_password'
+      ? String((config.authConfig as Record<string, unknown>)?.username ?? '')
+      : String(config.clientId ?? '')
+  return `${config.terminalCode}:${principal}`
+}
+
+function buildBody(config: ResolvedTerminalConfig): URLSearchParams {
+  const auth = (config.authConfig ?? {}) as Record<string, unknown>
+  const body = new URLSearchParams()
+  if (config.clientId) body.set('client_id', config.clientId)
+  if (config.scope) body.set('scope', config.scope)
+
+  if (config.authType === 'oauth2_password') {
+    body.set('grant_type', 'password')
+    body.set('username', String(auth.username ?? ''))
+    body.set('password', String(auth.password ?? ''))
+  } else {
+    body.set('grant_type', 'client_credentials')
+    if (auth.clientSecret) body.set('client_secret', String(auth.clientSecret))
+  }
+  return body
+}
+
+/** Extract the `AADB2C…` / OAuth error code from a token error body. */
+function extractErrorCode(text: string): string | undefined {
+  const m = text.match(/AADB2C\d+|AADSTS\d+/)
+  if (m) return m[0]
+  try {
+    const j = JSON.parse(text) as { error?: string }
+    return j.error
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Acquire (and cache) an OAuth access token for the terminal. Supports
+ * Azure B2C ROPC (password grant) and client-credentials. Surfaces the exact
+ * `AADB2C…` code on failure (e.g. AADB2C90225 for a not-yet-changed password).
+ */
+export async function acquireToken(config: ResolvedTerminalConfig): Promise<string> {
+  if (!config.tokenUrl) throw new TerminalAuthError('Terminal config has no tokenUrl')
+
+  const key = cacheKey(config)
+  const cached = tokenCache.get(key)
+  const now = Date.now()
+  if (cached && cached.expiresAt > now + 30_000) return cached.token
+
+  const { status, ok, text } = await n4Request(
+    config.tokenUrl,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: buildBody(config).toString(),
+    },
+    { proxyUrl: config.proxyUrl, label: `${config.terminalCode} token` },
+  )
+
+  if (!ok) {
+    throw new TerminalAuthError(
+      `Token request failed (${status})${extractErrorCode(text) ? `: ${extractErrorCode(text)}` : ''}`,
+      extractErrorCode(text),
+    )
+  }
+
+  let parsed: { access_token?: string; expires_in?: string | number }
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new TerminalAuthError('Token response was not JSON')
+  }
+  if (!parsed.access_token) {
+    throw new TerminalAuthError('No access_token in token response', extractErrorCode(text))
+  }
+
+  const ttlSeconds = Number(parsed.expires_in ?? 3600)
+  tokenCache.set(key, { token: parsed.access_token, expiresAt: now + ttlSeconds * 1000 })
+  return parsed.access_token
+}
+
+/** Clear the cached token for a terminal (used after auth failures). */
+export function invalidateToken(config: ResolvedTerminalConfig): void {
+  tokenCache.delete(cacheKey(config))
+}