@freighttech/terminal-tracking 0.7.0

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

@@ -0,0 +1,219 @@
+import type {
+  TerminalAdapter,
+  TerminalFetchResult,
+  TerminalFetchedEvent,
+  TerminalAdapterTestResult,
+  ResolvedTerminalConfig,
+  NormalizedVesselVisit,
+} from '../../terminal-adapter'
+import type { IncosContainer, IncosContainerResponse, IncosVesselVisitResponse } from './types'
+import { basicAuthHeader, BctAuthError } from './auth/basic'
+import { mapContainerToEvents, normalizeIncosVesselVisit, splitVisitRef } from './incos-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 INCOS API that fronts BCT (Bałtycki Terminal
+ * Kontenerowy, Gdynia). One instance serves every INCOS terminal configured with
+ * `adapterType: 'bct'`; per-terminal differences live in the TerminalConfig.
+ *
+ * Differences from the N4 adapter that shape this code:
+ *  - Auth is plain HTTP Basic (see ./auth/basic.ts), not an OAuth2 Bearer grant —
+ *    there is no token endpoint or cache; the header is rebuilt per request.
+ *  - The container lookup is a per-container path GET (`/rest-container/container/
+ *    {nbr}`) returning a single snapshot, so `fetchEventsBatch` loops
+ *    `fetchEvents` (bounded upstream by the per-terminal limiter), like GCT.
+ *  - INCOS keys a vessel visit on (vessel, voyage), so the container mapping packs
+ *    both into the visit ref (`CODE/VOY`) and `fetchVesselVisit` splits it back;
+ *    enrichment runs only when the TerminalConfig sets `endpoints.vessel`.
+ */
+export class BctTerminalAdapter implements TerminalAdapter {
+  readonly adapterType = 'bct'
+
+  readonly defaultEndpoints = {
+    // INCOS's container-lookup base occupies the generic `unit` slot; the
+    // container number is appended as a path segment per request.
+    unit: '/rest-container/container',
+    // Vessel-visit lookup base; vesselCode + voyage are appended per request.
+    // Enrichment only runs when the TerminalConfig also sets `endpoints.vessel`
+    // (the service gates on it) — this is the path used when it does.
+    vessel: '/rest-vesselvisit/vesselvisit',
+  }
+
+  private containerUrl(containerNumber: string, config: ResolvedTerminalConfig): string {
+    const path = config.endpoints?.unit?.trim() || this.defaultEndpoints.unit
+    return `${joinUrl(config.baseUrl, path)}/${encodeURIComponent(containerNumber)}`
+  }
+
+  private vesselUrl(vesselCode: string, voyage: string, config: ResolvedTerminalConfig): string {
+    const path = config.endpoints?.vessel?.trim() || this.defaultEndpoints.vessel
+    return `${joinUrl(config.baseUrl, path)}/${encodeURIComponent(vesselCode)}/${encodeURIComponent(voyage)}`
+  }
+
+  private async getContainer(
+    containerNumber: string,
+    config: ResolvedTerminalConfig,
+  ): Promise<IncosContainer | null> {
+    const { status, ok, text } = await n4Request(
+      this.containerUrl(containerNumber, config),
+      {
+        method: 'GET',
+        headers: {
+          Authorization: basicAuthHeader(config),
+          Accept: 'application/json',
+        },
+      },
+      { proxyUrl: config.proxyUrl, label: `${config.terminalCode} container` },
+    )
+
+    if (status === 401 || status === 403) {
+      throw new BctAuthError(`INCOS container lookup unauthorized (${status}) for ${config.terminalCode}`)
+    }
+    if (!ok) {
+      throw new Error(`INCOS container lookup failed (${status}) for ${config.terminalCode}`)
+    }
+
+    let parsed: IncosContainerResponse
+    try {
+      parsed = JSON.parse(text) as IncosContainerResponse
+    } catch {
+      throw new Error(`INCOS container response was not valid JSON for ${config.terminalCode}`)
+    }
+
+    // An unknown container does NOT error: INCOS echoes it back as a SUCCESS
+    // envelope with the number filled in and every other field null (observed
+    // live) — so the timestamp-gating in `mapContainerToEvents` yields no events
+    // and the job keeps polling. A genuine ERROR envelope (bad request etc.) is
+    // treated the same "not found → no events" way rather than thrown, so one odd
+    // response can't sink a poll. (Bad credentials surface earlier as a 401.)
+    if (String(parsed.status ?? '').toUpperCase() !== 'SUCCESS') return null
+    const data = parsed.data
+    if (!data || !data.container_nbr) return null
+    return data
+  }
+
+  async fetchEvents(input: {
+    containerNumber: string
+    config: ResolvedTerminalConfig
+  }): Promise<TerminalFetchResult> {
+    const { containerNumber, config } = input
+    const container = await this.getContainer(containerNumber, config)
+    const events = container ? mapContainerToEvents(container, config) : []
+
+    terminalLogger.debug('bct fetchEvents', {
+      terminalCode: config.terminalCode,
+      container: containerNumber,
+      found: Boolean(container),
+      events: events.length,
+    })
+
+    return { events, containerNumber }
+  }
+
+  /**
+   * INCOS 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 —
+   * except an auth error, which is fatal to the batch (bad credentials would just
+   * repeat for every container).
+   */
+  async fetchEventsBatch(input: {
+    containerNumbers: string[]
+    config: ResolvedTerminalConfig
+  }): Promise<{ events: TerminalFetchedEvent[] }> {
+    const { containerNumbers, config } = input
+    if (containerNumbers.length === 0) return { events: [] }
+
+    const events: TerminalFetchedEvent[] = []
+    for (const containerNumber of containerNumbers) {
+      try {
+        const result = await this.fetchEvents({ containerNumber, config })
+        events.push(...result.events)
+      } catch (err) {
+        if (err instanceof BctAuthError) throw err
+        terminalLogger.warn('bct fetchEventsBatch: container failed', {
+          terminalCode: config.terminalCode,
+          container: containerNumber,
+          message: err instanceof Error ? err.message : String(err),
+        })
+      }
+    }
+    return { events }
+  }
+
+  /**
+   * Resolve a vessel visit for a `CODE/VOY` ref (as produced by the container
+   * mapping's `visitRefIn`/`visitRefOut`). INCOS keys visits by (vesselCode,
+   * voyage), so the ref is split back into the two path segments. Returns null
+   * when the ref is malformed or INCOS reports no such visit (or its per-caller
+   * vessel-lookup rate limit is hit — an ERROR envelope). Vessel-visit dates are
+   * `YYYY-MM-DD HH:MM:SS`, parsed by `normalizeIncosVesselVisit`.
+   */
+  async fetchVesselVisit(input: {
+    visitRef: string
+    config: ResolvedTerminalConfig
+  }): Promise<NormalizedVesselVisit | null> {
+    const { visitRef, config } = input
+    const parts = splitVisitRef(visitRef)
+    if (!parts) return null
+
+    const { status, ok, text } = await n4Request(
+      this.vesselUrl(parts.vesselCode, parts.voyage, config),
+      { method: 'GET', headers: { Authorization: basicAuthHeader(config), Accept: 'application/json' } },
+      { proxyUrl: config.proxyUrl, label: `${config.terminalCode} vesselvisit` },
+    )
+
+    if (status === 401 || status === 403) {
+      throw new BctAuthError(`INCOS vessel lookup unauthorized (${status}) for ${config.terminalCode}`)
+    }
+    if (!ok) {
+      throw new Error(`INCOS vessel lookup failed (${status}) for ${config.terminalCode}`)
+    }
+
+    let parsed: IncosVesselVisitResponse
+    try {
+      parsed = JSON.parse(text) as IncosVesselVisitResponse
+    } catch {
+      throw new Error(`INCOS vessel response was not valid JSON for ${config.terminalCode}`)
+    }
+    if (String(parsed.status ?? '').toUpperCase() !== 'SUCCESS' || !parsed.data) return null
+    return normalizeIncosVesselVisit(parsed.data, visitRef)
+  }
+
+  /**
+   * INCOS has no ping/health route, so probe the container endpoint with a
+   * placeholder number. Verified live: a wrong password returns HTTP 401, while
+   * an unknown container returns HTTP 200 with a SUCCESS envelope of nulls — so
+   * a 401/403 means the Basic credentials are wrong and any other outcome proves
+   * the host is reachable and the credentials are accepted. Missing credentials
+   * surface via `basicAuthHeader` throwing before any request.
+   */
+  async testConnection(config: ResolvedTerminalConfig): Promise<TerminalAdapterTestResult> {
+    const started = Date.now()
+    try {
+      const probe = 'TEST0000000'
+      const { status } = await n4Request(
+        this.containerUrl(probe, config),
+        { method: 'GET', headers: { Authorization: basicAuthHeader(config), Accept: 'application/json' } },
+        { proxyUrl: config.proxyUrl, label: `${config.terminalCode} test`, retries: 0 },
+      )
+      if (status === 401 || status === 403) {
+        return {
+          success: false,
+          message: `Authentication rejected (${status}) — check username/password`,
+          latencyMs: Date.now() - started,
+        }
+      }
+      return { success: true, message: `Reachable and authenticated (HTTP ${status})`, latencyMs: Date.now() - started }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return { success: false, message, latencyMs: Date.now() - started }
+    }
+  }
+}

package/src/modules/terminal_tracking/lib/adapters/bct/auth/basic.ts

@@ -0,0 +1,34 @@
+import type { ResolvedTerminalConfig } from '../../../terminal-adapter'
+
+/**
+ * INCOS authenticates every call with plain HTTP Basic (`-u user:password` in
+ * the vendor docs). There is no token endpoint or cache — the header is derived
+ * from the decrypted `auth_config` on each request. Credentials live in
+ * `auth_config` as `{ username, password }` (encrypted at rest; see
+ * encryption.ts).
+ */
+
+export class BctAuthError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'BctAuthError'
+  }
+}
+
+/**
+ * Build the `Authorization: Basic <base64(user:pass)>` header for a config.
+ * Throws `BctAuthError` when either credential is missing, so a misconfigured
+ * terminal fails with a clear message rather than a silent 401.
+ */
+export function basicAuthHeader(config: ResolvedTerminalConfig): string {
+  const auth = (config.authConfig ?? {}) as Record<string, unknown>
+  const username = String(auth.username ?? '')
+  const password = String(auth.password ?? '')
+  if (!username || !password) {
+    throw new BctAuthError(
+      `BCT/INCOS config ${config.terminalCode} is missing username/password in auth_config`,
+    )
+  }
+  const token = Buffer.from(`${username}:${password}`, 'utf8').toString('base64')
+  return `Basic ${token}`
+}

package/src/modules/terminal_tracking/lib/adapters/bct/incos-semantics.ts

@@ -0,0 +1,291 @@
+import type { IncosContainer, IncosVesselVisit } from './types'
+import { DEFAULT_TERMINAL_TIMEZONE, zonedNaiveToUtc } from '../zoned-time'
+import type {
+  TerminalFetchedEvent,
+  ResolvedTerminalConfig,
+  NormalizedVesselVisit,
+} from '../../terminal-adapter'
+import type {
+  TerminalEventType,
+  TerminalEventClassifierCode,
+  TerminalModeOfTransport,
+} from '../../../data/entities'
+
+/**
+ * INCOS returns a container *state snapshot*, not a timestamped milestone stream
+ * (much like GCT). We emit only the container's CURRENT milestone — its arrival
+ * (`in_yard_date`) while it is on the terminal, or its departure
+ * (`out_yard_date`) once it has left — mirroring N4's `/unit` current-state row,
+ * rather than synthesizing extra states we cannot timestamp. INCOS has no
+ * separate loaded-onto-transport timestamp (N4's "Loaded" column), so no `LOAD`
+ * event.
+ *
+ * The arrival is refined by `in_yard_type` to match N4's vocabulary: a vessel
+ * arrival is a discharge (`DISC` → `equipment.discharged`), a truck/rail arrival
+ * is a gate-in (`GTIN` → `equipment.gate_in`). The departure is `DEPA`
+ * (`transport.departed`). All three `eventCode`s are the ones the service maps
+ * via n4-semantics `semanticEventIdFor`, so no adapter-specific downstream
+ * wiring is needed.
+ */
+
+type MilestoneSpec = {
+  eventType: TerminalEventType
+  eventCode: string
+  classifier: TerminalEventClassifierCode
+}
+
+const GATE_IN: MilestoneSpec = { eventType: 'EQUIPMENT', eventCode: 'GTIN', classifier: 'ACT' }
+const DISCHARGED: MilestoneSpec = { eventType: 'EQUIPMENT', eventCode: 'DISC', classifier: 'ACT' }
+const DEPARTED: MilestoneSpec = { eventType: 'TRANSPORT', eventCode: 'DEPA', classifier: 'ACT' }
+
+/** The container's direction of travel. */
+export type IncosCargoDirection = 'import' | 'export'
+
+/**
+ * Map INCOS `category` to a direction. Unlike GCT (which infers from a status
+ * prefix), INCOS states it explicitly: `E` = export, `I`/`X` = import. Blank or
+ * unknown yields null.
+ */
+export function directionFromCategory(category: string | null | undefined): IncosCargoDirection | null {
+  const c = (category ?? '').trim().toUpperCase()
+  if (!c) return null
+  if (c === 'E') return 'export'
+  if (c === 'I' || c === 'X') return 'import'
+  return null
+}
+
+/**
+ * Map an INCOS yard-move type (`in_yard_type` / `out_yard_type`) to a mode of
+ * transport: `T` truck, `V` vessel, `R` rail. Blank/unknown yields null.
+ */
+export function modeFromYardType(type: string | null | undefined): TerminalModeOfTransport | null {
+  const t = (type ?? '').trim().toUpperCase()
+  if (t === 'T') return 'TRUCK'
+  if (t === 'V') return 'VESSEL'
+  if (t === 'R') return 'RAIL'
+  return null
+}
+
+/**
+ * Parse an INCOS datetime — `DD-MM-YYYY HH:MI` (optionally with seconds), e.g.
+ * `03-05-2020 03:28`. INCOS returns terminal-local time without an offset, so we
+ * interpret it in the terminal's timezone (Europe/Warsaw by default) and return
+ * the corresponding UTC instant. Returns null when empty or the shape does not
+ * match (a strict match avoids `Date.parse` misreading the day-first order as
+ * month-first).
+ */
+export function parseIncosDateTime(
+  value: string | null | undefined,
+  timeZone: string = DEFAULT_TERMINAL_TIMEZONE,
+): Date | null {
+  if (!value) return null
+  const m = /^(\d{2})-(\d{2})-(\d{4})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value.trim())
+  if (!m) return null
+  const [, dd, mm, yyyy, hh, mi, ss] = m
+  return zonedNaiveToUtc(+yyyy, +mm, +dd, +hh, +mi, ss ? +ss : 0, timeZone)
+}
+
+/**
+ * Parse an INCOS **vessel-visit** datetime — `YYYY-MM-DD HH:MM[:SS]`, e.g.
+ * `2026-08-13 18:00:00`. This is a DIFFERENT format from the container endpoint's
+ * day-first `DD-MM-YYYY HH:MI` (confirmed against the live API). Terminal-local,
+ * no offset → interpreted in the terminal's timezone, consistent with
+ * `parseIncosDateTime`.
+ */
+export function parseIncosVesselDateTime(
+  value: string | null | undefined,
+  timeZone: string = DEFAULT_TERMINAL_TIMEZONE,
+): Date | null {
+  if (!value) return null
+  const m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value.trim())
+  if (!m) return null
+  const [, yyyy, mm, dd, hh, mi, ss] = m
+  return zonedNaiveToUtc(+yyyy, +mm, +dd, +hh, +mi, ss ? +ss : 0, timeZone)
+}
+
+/**
+ * Encode an INCOS vessel visit key. INCOS looks a visit up by (vesselCode,
+ * voyage), so both are packed into one visit ref as `CODE/VOY` (vessel codes and
+ * voyages contain no `/`). Returns null unless both parts are present.
+ */
+export function combinedVisitRef(
+  code: string | null | undefined,
+  voyage: string | null | undefined,
+): string | null {
+  const c = (code ?? '').trim()
+  const v = (voyage ?? '').trim()
+  return c && v ? `${c}/${v}` : null
+}
+
+/** Split a `CODE/VOY` visit ref back into its parts (on the first `/`). */
+export function splitVisitRef(visitRef: string): { vesselCode: string; voyage: string } | null {
+  const i = visitRef.indexOf('/')
+  if (i <= 0 || i >= visitRef.length - 1) return null
+  return { vesselCode: visitRef.slice(0, i), voyage: visitRef.slice(i + 1) }
+}
+
+/**
+ * Normalize an INCOS vessel-visit payload into the shared `NormalizedVesselVisit`.
+ * INCOS has no `phase`, `beginReceive`, or `dryCutoff`, so those are null.
+ */
+export function normalizeIncosVesselVisit(
+  data: IncosVesselVisit,
+  visitRef: string,
+): NormalizedVesselVisit {
+  return {
+    visitRef,
+    vesselName: data.vessel_name ?? null,
+    ibVoyage: data.in_voy ?? null,
+    obVoyage: data.out_voy ?? null,
+    line: data.line_code ?? null,
+    phase: null,
+    eta: parseIncosVesselDateTime(data.eta),
+    etd: parseIncosVesselDateTime(data.etd),
+    ata: parseIncosVesselDateTime(data.ata),
+    atd: parseIncosVesselDateTime(data.atd),
+    beginReceive: null,
+    dryCutoff: null,
+    rawData: { ...data },
+  }
+}
+
+/** Split a `;`-separated INCOS list, dropping blanks. */
+function splitList(value: string | null | undefined): string[] {
+  if (!value) return []
+  return value
+    .split(';')
+    .map((s) => s.trim())
+    .filter((s) => s !== '')
+}
+
+function buildSourceEventId(terminalCode: string, ufvGkey: string, eventCode: string): string {
+  return `${terminalCode}:${ufvGkey}:${eventCode}`
+}
+
+/** Per-milestone view of the snapshot: which yard-type + vessel fields apply. */
+type MilestoneContext = {
+  yardType: string | null | undefined
+  vesselName: string | null | undefined
+  voyage: string | null | undefined
+}
+
+function baseEvent(
+  container: IncosContainer,
+  config: ResolvedTerminalConfig,
+  ufvGkey: string,
+  spec: MilestoneSpec,
+  eventDateTime: Date,
+  ctx: MilestoneContext,
+): TerminalFetchedEvent {
+  const seals = [container.seal1, container.seal2, container.seal3, container.seal4]
+    .filter((n): n is string => typeof n === 'string' && n.trim() !== '')
+    .map((number) => ({ number, source: config.terminalCode }))
+
+  const direction = directionFromCategory(container.category)
+
+  // Impediments ("stopki"). A customs HOLD is mapped to the direction-specific
+  // catalogue code (`CUSTOMS IMPORT/EXPORT HOLD`) so `lib/holds.ts` classifies it
+  // as a critical customs hold instead of the "unknown" fallback. Per the INCOS
+  // docs `customs_status` is binary — empty, or `HOLD` when a customs hold is
+  // placed ("założony") — so this is the full fidelity INCOS offers: it is a real
+  // placed hold (not N4's routine auto-clearing "permission"), hence `critical`.
+  // Direction unknown → the import code (the dominant BCT flow). Raw `constraint`
+  // codes pass through and stay unclassified until INCOS documents them.
+  const customsHold =
+    String(container.customs_status ?? '').trim().toUpperCase() === 'HOLD'
+      ? [direction === 'export' ? 'CUSTOMS EXPORT HOLD' : 'CUSTOMS IMPORT HOLD']
+      : []
+  const impediments = [...customsHold, ...splitList(container.constraint)]
+
+  const vgm = typeof container.vgm_weight === 'number' ? container.vgm_weight : null
+
+  return {
+    source: 'terminal',
+    sourceEventId: buildSourceEventId(config.terminalCode, ufvGkey, spec.eventCode),
+    eventType: spec.eventType,
+    eventCode: spec.eventCode,
+    eventClassifierCode: spec.classifier,
+    eventDateTime,
+    // `ufvGkey` is the trimmed container number — reuse it so `containerNumber`
+    // and the dedup key can never disagree (and to avoid a raw-field cast).
+    containerNumber: ufvGkey,
+    ufvGkey,
+    // No S-code state on INCOS; the location is the closest transit signal.
+    transitState: container.actual_location ?? null,
+    visitState: null,
+    facilityCode: config.facilityCode ?? null,
+    facilityCodeListProvider: config.facilityCodeListProvider ?? null,
+    unlocode: config.unlocode ?? null,
+    // INCOS keys a vessel visit by (vesselCode, voyage), so encode both into the
+    // visit ref (`CODE/VOY`); the adapter's fetchVesselVisit splits it back apart.
+    visitRefIn: combinedVisitRef(container.vessel_code_in, container.vessel_visit_invoy),
+    visitRefOut: combinedVisitRef(container.vessel_code_out, container.vessel_visit_outvoy),
+    // Vessel name/voyage here are the container-snapshot values; when the config
+    // enables the vessel endpoint the service overwrites them (and adds ETA/ATA)
+    // from the resolved vessel visit.
+    vesselName: ctx.vesselName ?? null,
+    voyageNumber: ctx.voyage ?? null,
+    modeOfTransport: modeFromYardType(ctx.yardType),
+    seals: seals.length ? seals : null,
+    vgmWeightKg: vgm,
+    impediments: impediments.length ? impediments : null,
+    loadedAt: null,
+    // Preserve the full snapshot. `Category` (import/export) is the field
+    // `parseCargoCategory` reads to pick the vessel-visit side for enrichment.
+    rawData: { ...container, Category: direction ?? null },
+  }
+}
+
+/**
+ * Turn one INCOS container snapshot into zero, one, or two normalized events:
+ * a gate-in when `in_yard_date` is set, and a departed when `out_yard_date` is
+ * set. A snapshot with neither timestamp yields no events (nothing has provably
+ * happened yet). The dedup key is the container number — the container lookup
+ * carries no per-visit gkey, so (unlike GCT's `VisitNo`) a container that
+ * returns for a later visit reuses the same key.
+ */
+export function mapContainerToEvents(
+  container: IncosContainer,
+  config: ResolvedTerminalConfig,
+): TerminalFetchedEvent[] {
+  const containerNbr = (container.container_nbr ?? '').trim()
+  if (!containerNbr) return []
+  const ufvGkey = containerNbr
+
+  // Emit only the container's CURRENT milestone, mirroring N4's `/unit` (which
+  // returns a single row for the current transit state):
+  //  - departed (out_yard_date set) → just DEPA;
+  //  - still on terminal (in_yard_date set, no out) → its arrival (DISC/GTIN).
+  // Emitting BOTH the historical arrival and the departure on every poll would
+  // keep the job from ever completing — the service's `isFullyDeparted` requires
+  // *every* event in a poll to be DEPA — so a departed container would be polled
+  // forever, wasting requests against BCT's 10k/day cap. The arrival was already
+  // persisted (deduped by sourceEventId) while the box sat in the yard, so it
+  // stays on the timeline; only its redundant re-emission is dropped here.
+  const departed = parseIncosDateTime(container.out_yard_date)
+  if (departed) {
+    return [
+      baseEvent(container, config, ufvGkey, DEPARTED, departed, {
+        yardType: container.out_yard_type,
+        vesselName: container.vessel_name_out,
+        voyage: container.vessel_visit_outvoy,
+      }),
+    ]
+  }
+
+  const grounded = parseIncosDateTime(container.in_yard_date)
+  if (grounded) {
+    // A vessel arrival is a discharge; a truck/rail (or unspecified) arrival is a
+    // gate-in — matching how N4 splits DISC vs GTIN.
+    const arrivalSpec = modeFromYardType(container.in_yard_type) === 'VESSEL' ? DISCHARGED : GATE_IN
+    return [
+      baseEvent(container, config, ufvGkey, arrivalSpec, grounded, {
+        yardType: container.in_yard_type,
+        vesselName: container.vessel_name_in,
+        voyage: container.vessel_visit_invoy,
+      }),
+    ]
+  }
+
+  return []
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Response shapes for the INCOS API that fronts BCT (Bałtycki Terminal
+ * Kontenerowy, Gdynia). INCOS is a plain REST/JSON platform on `https://incos.pl`
+ * — unrelated to Navis N4 or the GCT FastAPI. Only the fields Phase 1
+ * (read-only container tracking) consumes are typed here; the full container
+ * payload is preserved verbatim into `rawData`.
+ *
+ * Source: "dokumentacja api INCOS" (BCT_INCOS_API_1, rev. 01.03.2021),
+ * endpoint "Sprawdź kontener" — `GET /rest-container/container/{nbr}`.
+ */
+
+/**
+ * One container as returned inside the `data` member of the container lookup.
+ * INCOS emits every field, using `null` for what it has no value for. Dates are
+ * `DD-MM-YYYY HH:MI` in terminal-local time (see `parseIncosDateTime`).
+ */
+export type IncosContainer = {
+  /** Container number. */
+  container_nbr?: string | null
+  /** ISO type code, e.g. `22G1`. */
+  container_iso_type?: string | null
+  /**
+   * Current location — free-form terminal text, inconsistent between the doc and
+   * the live API: observed values include `Y` (yard) and `OFF DOCK` (the vendor
+   * doc listed YARD/OFFDOCK/VESSEL/CFS). Stored verbatim into `transitState`;
+   * nothing branches on it.
+   */
+  actual_location?: string | null
+  /** Load status: E empty / F full. */
+  status?: string | null
+  /** Relation/category: E export / I,X import. */
+  category?: string | null
+  /** Shipping line code. */
+  line_code?: string | null
+  seal1?: string | null
+  seal2?: string | null
+  seal3?: string | null
+  seal4?: string | null
+  temp_min?: string | number | null
+  temp_max?: string | number | null
+  temp_set?: string | number | null
+  /** EU status Y/N. */
+  eu_status?: string | null
+  /** Customs hold: empty, or `HOLD` when a customs hold is set. */
+  customs_status?: string | null
+  /** Other constraints, a `;`-separated list (e.g. `STOPUC`). */
+  constraint?: string | null
+  /** IMO classes, `;`-separated. */
+  imo_class?: string | null
+  /** UN codes, `;`-separated (aligned to the imo_class order). */
+  un_code?: string | null
+  vgm_weight?: number | null
+  gross_weight?: number | null
+  net_weight?: number | null
+  /** Entry (gate-in / discharge) instant — `DD-MM-YYYY HH:MI`. */
+  in_yard_date?: string | null
+  /** How it entered: T truck / V vessel / R rail. */
+  in_yard_type?: string | null
+  /** Exit (gate-out / departure) instant — `DD-MM-YYYY HH:MI`. */
+  out_yard_date?: string | null
+  /** How it left: T truck / V vessel / R rail. */
+  out_yard_type?: string | null
+  vessel_code_in?: string | null
+  vessel_name_in?: string | null
+  vessel_visit_invoy?: string | null
+  vessel_code_out?: string | null
+  vessel_name_out?: string | null
+  vessel_visit_outvoy?: string | null
+  /** Whether a pre-advice already exists for the container in the terminal (Y/N). */
+  prelodge?: string | null
+  // Remaining fields are preserved via the index signature into rawData.
+  [key: string]: unknown
+}
+
+/**
+ * Vessel-visit data from `GET /rest-vesselvisit/vesselvisit/{code}/{voyage}`.
+ * NOTE: the live API returns dates as `YYYY-MM-DD HH:MM:SS` (terminal-local, no
+ * offset) — a DIFFERENT format from the container endpoint's `DD-MM-YYYY HH:MI`.
+ */
+export type IncosVesselVisit = {
+  vessel_code?: string | null
+  vessel_name?: string | null
+  in_voy?: string | null
+  out_voy?: string | null
+  line_code?: string | null
+  eta?: string | null
+  etd?: string | null
+  ata?: string | null
+  atd?: string | null
+  [key: string]: unknown
+}
+
+/** `GET /rest-vesselvisit/vesselvisit/{code}/{voyage}` response body. */
+export type IncosVesselVisitResponse = {
+  data?: IncosVesselVisit | null
+  status?: string | null
+}
+
+/**
+ * The INCOS envelope shared by reads and writes. For the container lookup,
+ * `data` is a single container object (not an array); `status` is `SUCCESS` on
+ * a hit and `ERROR` otherwise (the payload then carries an `error` block).
+ */
+export type IncosContainerResponse = {
+  data?: IncosContainer | null
+  status?: string | null
+  error?: {
+    type?: number | null
+    message?: string | null
+    fieldErrList?: string | null
+    fieldName?: string | null
+  } | null
+}