@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/lib/adapters/gct/__tests__/adapter.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+
+// The adapter's fetches run through `n4Request`, which drives undici's `fetch`.
+// Mock the undici module, keeping the real ProxyAgent/Agent so the 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 { GctTerminalAdapter } from '../adapter'
+import type { ResolvedTerminalConfig } from '../../../terminal-adapter'
+
+let counter = 0
+function cfg(overrides: Partial<ResolvedTerminalConfig> = {}): ResolvedTerminalConfig {
+  // Unique terminalCode per config to bypass the process-level token cache.
+  return {
+    terminalCode: `gcttest-${counter++}`,
+    adapterType: 'gct',
+    displayName: 'GCT',
+    baseUrl: 'https://api.gct.example',
+    proxyUrl: null,
+    endpoints: { unit: '/gctapi/GetContainerDetails' },
+    authType: 'gct_token',
+    // Authenticator secret (base32) — GCT's login takes a TOTP code as password.
+    // `JBSWY3DPEHPK3PXP` is the canonical RFC test seed ("Hello!").
+    authConfig: { companyCode: 'ACME', loginName: 'user', totpSecret: 'JBSWY3DPEHPK3PXP' },
+    rateLimitRequests: 60,
+    rateLimitWindowSeconds: 60,
+    unlocode: 'PLGDY',
+    ...overrides,
+  }
+}
+
+const FUTURE = '2999-01-01T00:00:00Z'
+const PAST = '2000-01-01T00:00:00Z'
+
+function tokenResponse(token = 'tok-123', expires: string = FUTURE) {
+  return new Response(JSON.stringify({ token, token_type: 'Bearer', expires }), { status: 200 })
+}
+function detailsResponse(containers: unknown[]) {
+  return new Response(JSON.stringify({ Total: containers.length, Containers: containers }), { status: 200 })
+}
+
+const isAuthCall = (c: any[]) => (c[1] as any)?.method === 'GET'
+const isDetailsCall = (c: any[]) => (c[1] as any)?.method === 'POST'
+// Mint (full auth) vs refresh (keep-alive) are both GET — tell them apart by URL.
+const isMintCall = (c: any[]) => String(c[0]).includes('/gctapi/Auth')
+const isRefreshCall = (c: any[]) => String(c[0]).includes('/gctapi/ping')
+
+afterEach(() => fetchMock.mockReset())
+
+describe('GctTerminalAdapter.testConnection', () => {
+  // TC-TRACK-301
+  it('mints a token and reports success; a generated TOTP code goes in the path, token in the Authorization header', async () => {
+    fetchMock.mockResolvedValueOnce(tokenResponse('abc'))
+    const config = cfg()
+    const res = await new GctTerminalAdapter().testConnection(config)
+
+    expect(res.success).toBe(true)
+    const authCall = fetchMock.mock.calls.find(isAuthCall)!
+    // company/login in the path; the password segment is a fresh 6-digit TOTP code.
+    expect(String(authCall[0])).toMatch(/\/gctapi\/Auth\/ACME\/user\/\d{6}$/)
+    // The raw authenticator secret must NEVER appear in the URL — only the code.
+    expect(String(authCall[0])).not.toContain('JBSWY3DPEHPK3PXP')
+  })
+
+  it('honours a legacy static loginPassword when no totpSecret is configured', async () => {
+    fetchMock.mockResolvedValueOnce(tokenResponse('abc'))
+    const config = cfg({ authConfig: { companyCode: 'ACME', loginName: 'user', loginPassword: 'legacy-pass' } })
+    const res = await new GctTerminalAdapter().testConnection(config)
+
+    expect(res.success).toBe(true)
+    const authCall = fetchMock.mock.calls.find(isAuthCall)!
+    expect(String(authCall[0])).toContain('/gctapi/Auth/ACME/user/legacy-pass')
+  })
+
+  it('reports failure with only the status (never the secret) on a bad token', async () => {
+    fetchMock.mockResolvedValueOnce(new Response('nope', { status: 403 }))
+    const res = await new GctTerminalAdapter().testConnection(cfg())
+    expect(res.success).toBe(false)
+    expect(res.message).toContain('403')
+    expect(res.message).not.toContain('JBSWY3DPEHPK3PXP')
+  })
+
+  it('fails clearly when auth_config is missing credentials', async () => {
+    const res = await new GctTerminalAdapter().testConnection(cfg({ authConfig: {} }))
+    expect(res.success).toBe(false)
+    expect(res.message).toMatch(/companyCode|totpSecret/)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+})
+
+describe('GctTerminalAdapter.fetchEvents', () => {
+  // TC-TRACK-306 (mapping + Authorization header form)
+  it('replays the raw token in the Authorization header and maps the container', async () => {
+    fetchMock.mockResolvedValueOnce(tokenResponse('tok-xyz'))
+    fetchMock.mockResolvedValueOnce(
+      detailsResponse([{ CntrID: 'GCTU1234567', VisitNo: 'V9', GroundingDateTime: '2026-08-10T09:30:00Z' }]),
+    )
+
+    const { events } = await new GctTerminalAdapter().fetchEvents({
+      containerNumber: 'GCTU1234567',
+      config: cfg(),
+    })
+
+    expect(events).toHaveLength(1)
+    expect(events[0].sourceEventId).toBe(events[0].sourceEventId) // stable
+    expect(events[0].eventCode).toBe('GTIN')
+
+    const detailsCall = fetchMock.mock.calls.find(isDetailsCall)!
+    expect((detailsCall[1] as any).headers.Authorization).toBe('tok-xyz')
+    expect(JSON.parse((detailsCall[1] as any).body)).toMatchObject({ CntrID: 'GCTU1234567' })
+  })
+
+  // TC-TRACK-309
+  it('returns [] for an empty/malformed Containers payload without throwing', async () => {
+    fetchMock.mockResolvedValueOnce(tokenResponse())
+    fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({ Total: 0 }), { status: 200 }))
+    const { events } = await new GctTerminalAdapter().fetchEvents({ containerNumber: 'X', config: cfg() })
+    expect(events).toEqual([])
+  })
+
+  it('throws on a non-JSON details body', async () => {
+    fetchMock.mockResolvedValueOnce(tokenResponse())
+    fetchMock.mockResolvedValueOnce(new Response('<html>500</html>', { status: 200 }))
+    await expect(
+      new GctTerminalAdapter().fetchEvents({ containerNumber: 'X', config: cfg() }),
+    ).rejects.toThrow(/valid JSON/)
+  })
+})
+
+describe('GctTerminalAdapter token cache + 401 handling', () => {
+  // TC-TRACK-305
+  it('reuses the cached token across calls, then re-acquires after a 401', async () => {
+    const config = cfg()
+    // 1st fetchEvents: token GET + details POST(200)
+    fetchMock.mockResolvedValueOnce(tokenResponse('t1'))
+    fetchMock.mockResolvedValueOnce(detailsResponse([]))
+    await new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config })
+    expect(fetchMock.mock.calls.filter(isAuthCall)).toHaveLength(1)
+
+    // 2nd fetchEvents: cache hit (no new token GET) + details POST that 401s
+    fetchMock.mockResolvedValueOnce(new Response('unauthorized', { status: 401 }))
+    await expect(
+      new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config }),
+    ).rejects.toThrow(/401/)
+    expect(fetchMock.mock.calls.filter(isAuthCall)).toHaveLength(1) // still cached until invalidated
+
+    // 3rd fetchEvents: the 401 invalidated the cache, so a fresh token is minted
+    fetchMock.mockResolvedValueOnce(tokenResponse('t2'))
+    fetchMock.mockResolvedValueOnce(detailsResponse([]))
+    await new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config })
+    expect(fetchMock.mock.calls.filter(isAuthCall)).toHaveLength(2)
+  })
+})
+
+describe('GctTerminalAdapter token refresh (keep-alive)', () => {
+  // TC-TRACK-307 — an expired token is refreshed via /gctapi/ping, not re-minted.
+  it('refreshes an expired token via /gctapi/ping instead of re-authenticating', async () => {
+    const config = cfg()
+    // 1st fetchEvents mints a token that is ALREADY expired (past `expires`).
+    fetchMock.mockResolvedValueOnce(tokenResponse('t-mint', PAST))
+    fetchMock.mockResolvedValueOnce(detailsResponse([]))
+    await new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config })
+
+    // 2nd fetchEvents: token is stale → keep-alive refresh returns a fresh token.
+    fetchMock.mockResolvedValueOnce(tokenResponse('t-refreshed', FUTURE)) // ping
+    fetchMock.mockResolvedValueOnce(detailsResponse([]))
+    await new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config })
+
+    expect(fetchMock.mock.calls.filter(isRefreshCall)).toHaveLength(1)
+    expect(fetchMock.mock.calls.filter(isMintCall)).toHaveLength(1) // no re-auth
+    const details = fetchMock.mock.calls.filter(isDetailsCall)
+    expect((details[1][1] as any).headers.Authorization).toBe('t-refreshed')
+  })
+
+  // TC-TRACK-308 — a failed refresh falls back to a full re-authentication.
+  it('re-authenticates when the refresh call fails', async () => {
+    const config = cfg()
+    fetchMock.mockResolvedValueOnce(tokenResponse('t1', PAST)) // mint (already expired)
+    fetchMock.mockResolvedValueOnce(detailsResponse([]))
+    await new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config })
+
+    fetchMock.mockResolvedValueOnce(new Response('unauthorized', { status: 401 })) // ping fails
+    fetchMock.mockResolvedValueOnce(tokenResponse('t2', FUTURE)) // re-auth mint
+    fetchMock.mockResolvedValueOnce(detailsResponse([]))
+    await new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config })
+
+    expect(fetchMock.mock.calls.filter(isRefreshCall)).toHaveLength(1) // tried once
+    expect(fetchMock.mock.calls.filter(isMintCall)).toHaveLength(2) // initial + re-auth
+    const details = fetchMock.mock.calls.filter(isDetailsCall)
+    expect((details[1][1] as any).headers.Authorization).toBe('t2')
+  })
+
+  it('re-authenticates when the refresh response carries no token', async () => {
+    const config = cfg()
+    fetchMock.mockResolvedValueOnce(tokenResponse('t1', PAST))
+    fetchMock.mockResolvedValueOnce(detailsResponse([]))
+    await new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config })
+
+    fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({ status: 'ok' }), { status: 200 })) // ping, no token
+    fetchMock.mockResolvedValueOnce(tokenResponse('t2', FUTURE))
+    fetchMock.mockResolvedValueOnce(detailsResponse([]))
+    await new GctTerminalAdapter().fetchEvents({ containerNumber: 'A', config })
+
+    expect(fetchMock.mock.calls.filter(isRefreshCall)).toHaveLength(1)
+    expect(fetchMock.mock.calls.filter(isMintCall)).toHaveLength(2)
+  })
+})
+
+describe('GctTerminalAdapter.fetchEventsBatch', () => {
+  it('loops per container and isolates a single container failure', async () => {
+    const config = cfg()
+    fetchMock.mockResolvedValueOnce(tokenResponse()) // up-front acquire
+    // container A (token cached now): details 500 → isolated
+    fetchMock.mockResolvedValueOnce(new Response('err', { status: 500 }))
+    // container B: details 200 with a mappable row
+    fetchMock.mockResolvedValueOnce(
+      detailsResponse([{ CntrID: 'B', VisitNo: 'VB', GroundingDateTime: '2026-08-10T09:30:00Z' }]),
+    )
+
+    const { events } = await new GctTerminalAdapter().fetchEventsBatch({
+      containerNumbers: ['A', 'B'],
+      config,
+    })
+    expect(events).toHaveLength(1)
+    expect(events[0].containerNumber).toBe('B')
+  })
+
+  it('fails the whole batch when the up-front token acquire fails', async () => {
+    fetchMock.mockResolvedValueOnce(new Response('nope', { status: 403 }))
+    await expect(
+      new GctTerminalAdapter().fetchEventsBatch({ containerNumbers: ['A', 'B'], config: cfg() }),
+    ).rejects.toThrow()
+  })
+})

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

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest'
+import { mapContainerToEvents, directionFromStatus, parseGctDateTime } from '../gct-semantics'
+import type { GctContainer } from '../types'
+import type { ResolvedTerminalConfig } from '../../../terminal-adapter'
+
+const config: ResolvedTerminalConfig = {
+  terminalCode: 'gct',
+  adapterType: 'gct',
+  displayName: 'Gdynia Container Terminal',
+  baseUrl: 'https://api.gct.example',
+  endpoints: { unit: '/gctapi/GetContainerDetails' },
+  authType: 'gct_token',
+  rateLimitRequests: 60,
+  rateLimitWindowSeconds: 60,
+  unlocode: 'PLGDY',
+}
+
+function container(partial: Partial<GctContainer>): GctContainer {
+  return { CntrID: 'GCTU1234567', VisitNo: 'V-001', ...partial }
+}
+
+describe('directionFromStatus', () => {
+  it('maps X* to export and I* to import', () => {
+    expect(directionFromStatus('XF')).toBe('export')
+    expect(directionFromStatus('XM')).toBe('export')
+    expect(directionFromStatus('IF')).toBe('import')
+  })
+  it('returns null for empty-no-purpose, unknown, and blank', () => {
+    expect(directionFromStatus('EM')).toBeNull()
+    expect(directionFromStatus('ZZ')).toBeNull()
+    expect(directionFromStatus('')).toBeNull()
+    expect(directionFromStatus(null)).toBeNull()
+  })
+  it('does not crash on the undocumented XI status', () => {
+    expect(directionFromStatus('XI')).toBe('export')
+  })
+})
+
+describe('parseGctDateTime', () => {
+  it('parses ISO-8601', () => {
+    expect(parseGctDateTime('2026-08-10T09:30:00Z')?.toISOString()).toBe('2026-08-10T09:30:00.000Z')
+  })
+  it('parses the N4-style "yyyy-mm-dd hh:mm" as terminal-local (Europe/Warsaw) → UTC', () => {
+    // 09:30 CEST (+02:00) on 2026-08-10 is 07:30 UTC.
+    expect(parseGctDateTime('2026-08-10 09:30')?.toISOString()).toBe('2026-08-10T07:30:00.000Z')
+  })
+  it('returns null for empty/garbage', () => {
+    expect(parseGctDateTime(null)).toBeNull()
+    expect(parseGctDateTime('  ')).toBeNull()
+    expect(parseGctDateTime('not-a-date')).toBeNull()
+  })
+})
+
+describe('mapContainerToEvents', () => {
+  // TC-TRACK-302
+  it('emits one gate_in (GTIN) event from GroundingDateTime, keyed on VisitNo', () => {
+    const events = mapContainerToEvents(
+      container({ GroundingDateTime: '2026-08-10T09:30:00Z', CntrStatus: 'IF', VGMWeight: 24000 }),
+      config,
+    )
+    expect(events).toHaveLength(1)
+    const ev = events[0]
+    expect(ev.eventType).toBe('EQUIPMENT')
+    expect(ev.eventCode).toBe('GTIN')
+    expect(ev.eventClassifierCode).toBe('ACT')
+    expect(ev.ufvGkey).toBe('V-001')
+    expect(ev.sourceEventId).toBe('gct:V-001:GTIN')
+    expect(ev.containerNumber).toBe('GCTU1234567')
+    expect(ev.unlocode).toBe('PLGDY')
+    expect(ev.vgmWeightKg).toBe(24000)
+    expect(ev.transitState).toBe('IF')
+    expect(ev.eventDateTime.toISOString()).toBe('2026-08-10T09:30:00.000Z')
+  })
+
+  // TC-TRACK-303
+  it('adds a departed (DEPA) event when PickupDateTime is present', () => {
+    const events = mapContainerToEvents(
+      container({ GroundingDateTime: '2026-08-10T09:30:00Z', PickupDateTime: '2026-08-12T14:00:00Z' }),
+      config,
+    )
+    expect(events.map((e) => e.eventCode)).toEqual(['GTIN', 'DEPA'])
+    const dep = events.find((e) => e.eventCode === 'DEPA')!
+    expect(dep.eventType).toBe('TRANSPORT')
+    expect(dep.sourceEventId).toBe('gct:V-001:DEPA')
+    expect(dep.eventDateTime.toISOString()).toBe('2026-08-12T14:00:00.000Z')
+  })
+
+  it('emits no events when neither timestamp is present', () => {
+    expect(mapContainerToEvents(container({ CntrStatus: 'XF' }), config)).toEqual([])
+  })
+
+  // TC-TRACK-304
+  it('passes HoldCodesList through as impediments (dropping blanks)', () => {
+    const events = mapContainerToEvents(
+      container({ GroundingDateTime: '2026-08-10T09:30:00Z', HoldCodesList: ['CUSTOMS', '', '  ', 'VGM'] }),
+      config,
+    )
+    expect(events[0].impediments).toEqual(['CUSTOMS', 'VGM'])
+  })
+
+  it('maps SealList to seal objects and preserves the full snapshot in rawData', () => {
+    const events = mapContainerToEvents(
+      container({
+        GroundingDateTime: '2026-08-10T09:30:00Z',
+        SealList: ['SEAL1'],
+        CntrStatus: 'XF',
+        VesselName: 'MSC ISABELLA',
+        GCTVoyage: 'V123',
+      }),
+      config,
+    )
+    const ev = events[0]
+    expect(ev.seals).toEqual([{ number: 'SEAL1', source: 'gct' }])
+    expect(ev.vesselName).toBe('MSC ISABELLA')
+    expect(ev.voyageNumber).toBe('V123')
+    expect(ev.modeOfTransport).toBe('VESSEL')
+    expect((ev.rawData as Record<string, unknown>).Category).toBe('export')
+    expect((ev.rawData as Record<string, unknown>).CntrID).toBe('GCTU1234567')
+  })
+
+  it('falls back to CntrID for the dedup key when VisitNo is missing', () => {
+    const events = mapContainerToEvents(
+      container({ VisitNo: null, GroundingDateTime: '2026-08-10T09:30:00Z' }),
+      config,
+    )
+    expect(events[0].ufvGkey).toBe('GCTU1234567')
+    expect(events[0].sourceEventId).toBe('gct:GCTU1234567:GTIN')
+  })
+
+  it('returns [] for a container with no CntrID', () => {
+    expect(mapContainerToEvents({ CntrID: '' } as GctContainer, config)).toEqual([])
+  })
+})

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

@@ -0,0 +1,152 @@
+import type {
+  TerminalAdapter,
+  TerminalFetchResult,
+  TerminalFetchedEvent,
+  TerminalAdapterTestResult,
+  ResolvedTerminalConfig,
+} from '../../terminal-adapter'
+import type { GctContainer, GctContainerDetailsResponse } from './types'
+import { acquireGctToken, invalidateGctToken, GctAuthError } from './auth/token'
+import { mapContainerToEvents } from './gct-semantics'
+import { n4Request } from '../n4/http'
+import { terminalLogger } from '../../logger'
+
+function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/$/, '')}/${path.replace(/^\//, '')}`
+}
+
+/**
+ * Config-driven adapter for the GCT (Gdynia Container Terminal) API. One
+ * instance serves every GCT terminal; per-terminal differences live in the
+ * TerminalConfig.
+ *
+ * Differences from the N4 adapter that shape this code:
+ *  - Auth is a path-minted token replayed in the `Authorization` header
+ *    (see ./auth/token.ts), not an OAuth2 Bearer grant.
+ *  - There is no fetch-many-by-container-number endpoint, so `fetchEventsBatch`
+ *    simply loops `fetchEvents` (bounded upstream by the per-terminal limiter).
+ *  - There is no vessel endpoint, so `fetchVesselVisit` is intentionally omitted
+ *    — the service feature-detects it and skips vessel resolution for GCT.
+ */
+export class GctTerminalAdapter implements TerminalAdapter {
+  readonly adapterType = 'gct'
+
+  readonly defaultEndpoints = {
+    // GCT's container-details endpoint occupies the generic `unit` slot.
+    unit: '/gctapi/GetContainerDetails',
+  }
+
+  private detailsUrl(config: ResolvedTerminalConfig): string {
+    const path = config.endpoints?.unit?.trim() || this.defaultEndpoints.unit
+    return joinUrl(config.baseUrl, path)
+  }
+
+  private async getContainerDetails(
+    containerNumber: string,
+    config: ResolvedTerminalConfig,
+    token: string,
+  ): Promise<GctContainer[]> {
+    const { status, ok, text } = await n4Request(
+      this.detailsUrl(config),
+      {
+        method: 'POST',
+        headers: {
+          Authorization: token,
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ CntrID: containerNumber, pageno: 1, pagesize: 100 }),
+      },
+      { proxyUrl: config.proxyUrl, label: `${config.terminalCode} GetContainerDetails` },
+    )
+
+    if (status === 401) {
+      invalidateGctToken(config)
+      throw new GctAuthError(`GetContainerDetails unauthorized (401) for ${config.terminalCode}`)
+    }
+    if (!ok) {
+      throw new Error(`GetContainerDetails failed (${status}) for ${config.terminalCode}`)
+    }
+
+    let parsed: GctContainerDetailsResponse
+    try {
+      parsed = JSON.parse(text) as GctContainerDetailsResponse
+    } catch {
+      throw new Error(`GetContainerDetails response was not valid JSON for ${config.terminalCode}`)
+    }
+    return Array.isArray(parsed.Containers) ? parsed.Containers : []
+  }
+
+  async fetchEvents(input: {
+    containerNumber: string
+    config: ResolvedTerminalConfig
+  }): Promise<TerminalFetchResult> {
+    const { containerNumber, config } = input
+    const token = await acquireGctToken(config)
+    const containers = await this.getContainerDetails(containerNumber, config, token)
+
+    const events: TerminalFetchedEvent[] = []
+    for (const container of containers) {
+      events.push(...mapContainerToEvents(container, config))
+    }
+
+    terminalLogger.debug('gct fetchEvents', {
+      terminalCode: config.terminalCode,
+      container: containerNumber,
+      rows: containers.length,
+      events: events.length,
+    })
+
+    return { events, containerNumber }
+  }
+
+  /**
+   * GCT has no batch-by-container-number call, so fetch each container in turn.
+   * Kept as a distinct method (rather than falling through to per-container in
+   * the service) so the scheduler's batch path stays a single call site; the
+   * per-terminal rate limiter still throttles the underlying requests. A single
+   * container's failure is isolated so one bad number can't sink the whole poll.
+   */
+  async fetchEventsBatch(input: {
+    containerNumbers: string[]
+    config: ResolvedTerminalConfig
+  }): Promise<{ events: TerminalFetchedEvent[] }> {
+    const { containerNumbers, config } = input
+    if (containerNumbers.length === 0) return { events: [] }
+
+    // Acquire once up front so a genuine auth failure fails the whole batch
+    // (marking the job failed) instead of being swallowed 100× as per-container
+    // data errors below.
+    await acquireGctToken(config)
+
+    const events: TerminalFetchedEvent[] = []
+    for (const containerNumber of containerNumbers) {
+      try {
+        const result = await this.fetchEvents({ containerNumber, config })
+        events.push(...result.events)
+      } catch (err) {
+        // An auth error is fatal to the batch (token revoked/expired mid-run);
+        // let it propagate. Data/transport errors are isolated so one bad
+        // container can't sink the poll for the rest.
+        if (err instanceof GctAuthError) throw err
+        terminalLogger.warn('gct fetchEventsBatch: container failed', {
+          terminalCode: config.terminalCode,
+          container: containerNumber,
+          message: err instanceof Error ? err.message : String(err),
+        })
+      }
+    }
+    return { events }
+  }
+
+  async testConnection(config: ResolvedTerminalConfig): Promise<TerminalAdapterTestResult> {
+    const started = Date.now()
+    try {
+      await acquireGctToken(config)
+      return { success: true, message: 'Token acquired', latencyMs: Date.now() - started }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return { success: false, message, latencyMs: Date.now() - started }
+    }
+  }
+}