@freighttech/terminal-tracking 0.7.0

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

@@ -0,0 +1,124 @@
+/**
+ * Load/pickup "STOP" flags for Navis N4 terminals (Baltic Hub / BCT).
+ *
+ * The N4 `/unit` endpoint gained three columns (Baltic Hub API update, Aug 2026)
+ * that state, per transport mode, whether the container currently CANNOT be
+ * loaded / picked up:
+ *
+ * - **Stop-Vsl**  — no loading onto a **vessel** (export blocked).
+ * - **Stop-Road** — no pickup by **road / truck**.
+ * - **Stop-Rail** — no pickup by **rail**.
+ *
+ * Unlike the `Unit Impediments` hold list (from which blocking is *inferred* via
+ * the catalogue in `./holds`), these are the terminal stating the restriction
+ * directly, so they are a cleaner mode-specific signal.
+ *
+ * Pure helper — no DI, no i18n, no React. Reads from the N4 row's `rawData` map
+ * (header → value) so the SAME parse serves the `/unit` parser, the availability
+ * logic (which runs on the persisted event's `rawData`), and the details drawer.
+ *
+ * ── Header + value format ───────────────────────────────────────────────────
+ * Confirmed against a real Baltic Hub `/unit` payload (2026-07): headers are
+ * `Stop-Vsl` / `Stop-Rail` / `Stop-Road`, values are the strings `"true"` /
+ * `"false"`. Header matching is still done **tolerantly** (case- and
+ * punctuation-insensitive) and value parsing treats any non-empty, non-falsy
+ * token as an active stop, so a minor terminal-side format change (or another
+ * N4 terminal spelling the columns differently) keeps working — everything
+ * keys off this one file.
+ */
+
+/** Transport mode a STOP flag applies to. */
+export type TerminalStopMode = 'vsl' | 'road' | 'rail'
+
+/**
+ * The three STOP flags for a container. `null` means the terminal did not report
+ * that column at all (older terminals / pre-update payloads) — distinct from
+ * `false`, which means the column was present and no restriction is active.
+ */
+export type TerminalStops = {
+  /** No loading onto a vessel (export). */
+  vsl: boolean | null
+  /** No pickup by road / truck. */
+  road: boolean | null
+  /** No pickup by rail. */
+  rail: boolean | null
+}
+
+/** All-unknown stops (nothing reported). */
+export const NO_STOPS: TerminalStops = { vsl: null, road: null, rail: null }
+
+/**
+ * Candidate column headers per mode, in normalized form (lower-case,
+ * non-alphanumerics stripped). First match wins. `stopvessel` is kept alongside
+ * `stopvsl` in case the header spells the word out.
+ */
+const STOP_HEADERS: Record<TerminalStopMode, readonly string[]> = {
+  vsl: ['stopvsl', 'stopvessel'],
+  road: ['stoproad'],
+  rail: ['stoprail'],
+}
+
+/** Values that mean "no stop" when the column is present. */
+const FALSY_TOKENS = new Set(['', '0', 'n', 'no', 'false', 'f', '-'])
+
+/** Normalize a header for tolerant matching: lower-case, drop non-alphanumerics. */
+function normalizeHeader(header: string): string {
+  return header.toLowerCase().replace(/[^a-z0-9]/g, '')
+}
+
+/** Interpret a present column value as an active stop (true) or not (false). */
+function isActiveStop(value: unknown): boolean {
+  if (value == null) return false
+  return !FALSY_TOKENS.has(String(value).trim().toLowerCase())
+}
+
+/**
+ * Parse the STOP flags out of an N4 row's `rawData` (header → value). Returns
+ * `null` for a mode whose column is absent, `false`/`true` when present.
+ */
+export function parseTerminalStops(rawData: Record<string, unknown> | null | undefined): TerminalStops {
+  if (!rawData) return { ...NO_STOPS }
+
+  const byNorm = new Map<string, unknown>()
+  for (const [key, value] of Object.entries(rawData)) byNorm.set(normalizeHeader(key), value)
+
+  const read = (mode: TerminalStopMode): boolean | null => {
+    for (const candidate of STOP_HEADERS[mode]) {
+      if (byNorm.has(candidate)) return isActiveStop(byNorm.get(candidate))
+    }
+    return null
+  }
+
+  return { vsl: read('vsl'), road: read('road'), rail: read('rail') }
+}
+
+/** True only when road pickup is explicitly stopped (not on null/false). */
+export function isRoadStopped(stops: TerminalStops): boolean {
+  return stops.road === true
+}
+
+/**
+ * Whether the set of *actively-stopped* modes differs between two snapshots.
+ * Drives the `equipment.stops_updated` event. Compares on truthiness, so
+ * `null` (unreported) and `false` (reported, not stopped) are equivalent —
+ * both mean "not stopped" — mirroring how `impedimentsChanged` treats a null
+ * and an empty hold list as equal. This keeps a first poll of containers that
+ * merely carry all-`false` STOP columns from emitting spurious change events.
+ */
+export function stopsChanged(prior: TerminalStops, next: TerminalStops): boolean {
+  const active = (v: boolean | null) => v === true
+  return (
+    active(prior.vsl) !== active(next.vsl) ||
+    active(prior.road) !== active(next.road) ||
+    active(prior.rail) !== active(next.rail)
+  )
+}
+
+/** The modes with an active stop, in vsl → road → rail order. */
+export function activeStopModes(stops: TerminalStops): TerminalStopMode[] {
+  const modes: TerminalStopMode[] = []
+  if (stops.vsl === true) modes.push('vsl')
+  if (stops.road === true) modes.push('road')
+  if (stops.rail === true) modes.push('rail')
+  return modes
+}

package/src/modules/terminal_tracking/lib/terminal-adapter.ts

@@ -0,0 +1,136 @@
+import type {
+  TerminalEventType,
+  TerminalEventClassifierCode,
+  TerminalEventSource,
+  FacilityCodeProvider,
+  TerminalModeOfTransport,
+  TerminalAuthType,
+  TerminalEndpoints,
+  TerminalSealInfo,
+} from '../data/entities'
+
+/**
+ * A terminal config with its `auth_config` already decrypted, handed to
+ * adapters so they never touch the ORM or encryption layer directly.
+ */
+export type ResolvedTerminalConfig = {
+  terminalCode: string
+  adapterType: string
+  displayName: string
+  baseUrl: string
+  /** Optional HTTP(S) forward proxy for this terminal's API calls. */
+  proxyUrl?: string | null
+  endpoints: TerminalEndpoints
+  authType: TerminalAuthType
+  tokenUrl?: string | null
+  scope?: string | null
+  clientId?: string | null
+  /** Decrypted secrets, e.g. { username, password } or { clientSecret } */
+  authConfig?: Record<string, unknown> | null
+  rateLimitRequests: number
+  rateLimitWindowSeconds: number
+  unlocode?: string | null
+  facilityCode?: string | null
+  facilityCodeListProvider?: FacilityCodeProvider | null
+}
+
+/** A normalized, terminal-sourced event ready to persist as a TerminalEvent. */
+export type TerminalFetchedEvent = {
+  source: TerminalEventSource
+  sourceEventId: string // '{terminalCode}:{ufvGkey}:{eventCode}'
+  eventType: TerminalEventType
+  eventCode: string
+  eventClassifierCode?: TerminalEventClassifierCode | null
+  eventDateTime: Date
+  containerNumber: string
+  ufvGkey: string
+  transitState?: string | null
+  visitState?: string | null
+  facilityCode?: string | null
+  facilityCodeListProvider?: FacilityCodeProvider | null
+  unlocode?: string | null
+  visitRefIn?: string | null
+  visitRefOut?: string | null
+  vesselName?: string | null
+  voyageNumber?: string | null
+  modeOfTransport?: TerminalModeOfTransport | null
+  seals?: TerminalSealInfo[] | null
+  vgmWeightKg?: number | null
+  impediments?: string[] | null
+  // When the container was loaded onto its transport (N4 `Loaded` column):
+  // export = onto the vessel, import = onto road/rail. Parsed regardless of the
+  // container's current transit state, so it survives past S60_LOADED.
+  loadedAt?: Date | null
+  // Nested vessel visit enrichment (from /VESSEL); populated by the service layer.
+  vesselVisit?: NormalizedVesselVisit | null
+  rawData?: Record<string, unknown> | null
+}
+
+/**
+ * A normalized N4 `/VESSEL` visit, keyed by visit ref. Carries the full vessel
+ * row: name, both voyages, line, phase, all four timestamps, plus the
+ * begin-receive / dry-cutoff window dates.
+ */
+export type NormalizedVesselVisit = {
+  visitRef: string
+  vesselName: string | null
+  ibVoyage: string | null
+  obVoyage: string | null
+  line: string | null
+  phase: string | null
+  eta: Date | null
+  etd: Date | null
+  ata: Date | null
+  atd: Date | null
+  beginReceive: Date | null
+  dryCutoff: Date | null
+  rawData: Record<string, unknown> | null
+}
+
+export type TerminalFetchResult = {
+  events: TerminalFetchedEvent[]
+  containerNumber: string
+}
+
+export type TerminalAdapterTestResult = {
+  success: boolean
+  message: string
+  latencyMs?: number
+}
+
+export interface TerminalAdapter {
+  /** Selects this adapter from the registry, e.g. 'n4'. */
+  readonly adapterType: string
+
+  /** Standard endpoint paths for this adapter family; used when a terminal config omits them. */
+  readonly defaultEndpoints: TerminalEndpoints
+
+  fetchEvents(input: {
+    containerNumber: string
+    config: ResolvedTerminalConfig
+  }): Promise<TerminalFetchResult>
+
+  /**
+   * Fetch events for many containers in a single call (N4 /unit accepts a
+   * comma-separated UNIT_NBR list). Optional: callers feature-detect and fall
+   * back to per-container `fetchEvents`. Each returned event carries its own
+   * `containerNumber` for grouping back onto the originating job.
+   */
+  fetchEventsBatch?(input: {
+    containerNumbers: string[]
+    config: ResolvedTerminalConfig
+  }): Promise<{ events: TerminalFetchedEvent[] }>
+
+  /**
+   * Resolve a single vessel visit by its visit reference. Optional: adapters
+   * that don't support a vessel endpoint omit it, and callers must feature-detect
+   * before invoking. Returns null when the endpoint is unconfigured or the visit
+   * is not found.
+   */
+  fetchVesselVisit?(input: {
+    visitRef: string
+    config: ResolvedTerminalConfig
+  }): Promise<NormalizedVesselVisit | null>
+
+  testConnection(config: ResolvedTerminalConfig): Promise<TerminalAdapterTestResult>
+}

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

@@ -0,0 +1,63 @@
+/**
+ * TOTP (RFC 6238) code generation for terminal adapters whose login expects an
+ * authenticator one-time code in place of a static password (e.g. GCT).
+ *
+ * This is a deliberate, self-contained COPY of the generation half of
+ * `packages/two-factor/src/modules/two_factor/lib/totp.ts` — kept in sync by
+ * hand. We copy rather than depend on `@freighttech/two-factor` so this backend
+ * tracking module stays dependency-light (only `fuse.js` + `undici`) and free of
+ * that package's Next/React/mikro-orm peer deps. The algorithm is pure Node
+ * `crypto`; only the consume-side pieces are copied (base32 decode + HOTP +
+ * `generateTotp`) — enrollment helpers (secret/QR generation, verification) live
+ * in the two-factor package and are not needed here.
+ *
+ * Parameters match a standard authenticator app: SHA1, 6 digits, 30s period.
+ */
+import crypto from 'crypto'
+
+// ── Base32 (RFC 4648, no padding) ──────────────────────────────────────────
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+
+/** Decode a base32 authenticator secret into its raw key bytes. */
+export function base32Decode(input: string): Buffer {
+  const clean = input.replace(/=+$/g, '').replace(/\s+/g, '').toUpperCase()
+  let bits = 0
+  let value = 0
+  const bytes: number[] = []
+  for (const ch of clean) {
+    const idx = BASE32_ALPHABET.indexOf(ch)
+    if (idx === -1) throw new Error('totp: invalid base32 character in secret')
+    value = (value << 5) | idx
+    bits += 5
+    if (bits >= 8) {
+      bytes.push((value >>> (bits - 8)) & 0xff)
+      bits -= 8
+    }
+  }
+  return Buffer.from(bytes)
+}
+
+// ── TOTP (RFC 6238) over HOTP (RFC 4226) ────────────────────────────────────
+export const TOTP_PERIOD_SECONDS = 30
+export const TOTP_DIGITS = 6
+
+function hotp(secret: Buffer, counter: number): string {
+  const buf = Buffer.alloc(8)
+  // 64-bit big-endian counter (JS bitops are 32-bit, so split hi/lo).
+  buf.writeUInt32BE(Math.floor(counter / 0x100000000), 0)
+  buf.writeUInt32BE(counter >>> 0, 4)
+  const hmac = crypto.createHmac('sha1', secret).update(buf).digest()
+  const offset = hmac[hmac.length - 1] & 0xf
+  const binary =
+    ((hmac[offset] & 0x7f) << 24) |
+    ((hmac[offset + 1] & 0xff) << 16) |
+    ((hmac[offset + 2] & 0xff) << 8) |
+    (hmac[offset + 3] & 0xff)
+  return (binary % 10 ** TOTP_DIGITS).toString().padStart(TOTP_DIGITS, '0')
+}
+
+/** Compute the current TOTP code for a base32 secret (default time: now). */
+export function generateTotp(base32Secret: string, nowMs: number = Date.now()): string {
+  const counter = Math.floor(nowMs / 1000 / TOTP_PERIOD_SECONDS)
+  return hotp(base32Decode(base32Secret), counter)
+}

package/src/modules/terminal_tracking/migrations/Migration20260609120000_terminal_tracking.ts

@@ -0,0 +1,104 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260609120000_terminal_tracking extends Migration {
+  override async up(): Promise<void> {
+    // ─── terminal_tracking_terminal_configs ──────────────────
+    this.addSql(`create table if not exists "terminal_tracking_terminal_configs" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "terminal_code" text not null,
+      "adapter_type" text not null,
+      "display_name" text not null,
+      "base_url" text not null,
+      "endpoints" jsonb not null,
+      "auth_type" text not null,
+      "token_url" text null,
+      "scope" text null,
+      "client_id" text null,
+      "auth_config" jsonb null,
+      "rate_limit_requests" integer not null default 200,
+      "rate_limit_window_seconds" integer not null default 60,
+      "unlocode" varchar(5) null,
+      "bic_codes" jsonb null,
+      "smdg_codes" jsonb null,
+      "name_aliases" jsonb null,
+      "is_active" boolean not null default true,
+      "created_at" timestamptz not null default now(),
+      "updated_at" timestamptz not null default now(),
+      "deleted_at" timestamptz null,
+      constraint "terminal_tracking_terminal_configs_pkey" primary key ("id")
+    );`)
+    this.addSql(`create index if not exists "tt_terminal_configs_org_tenant_idx" on "terminal_tracking_terminal_configs" ("organization_id", "tenant_id");`)
+    this.addSql(`create unique index if not exists "tt_terminal_configs_code_uniq" on "terminal_tracking_terminal_configs" ("organization_id", "tenant_id", "terminal_code");`)
+
+    // ─── terminal_tracking_jobs ──────────────────────────────
+    this.addSql(`create table if not exists "terminal_tracking_jobs" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "terminal_code" text not null,
+      "container_number" text not null,
+      "status" text not null default 'active',
+      "schedule" jsonb null,
+      "next_poll_at" timestamptz null,
+      "last_poll_at" timestamptz null,
+      "retry_count" integer not null default 0,
+      "error_history" jsonb null,
+      "created_at" timestamptz not null default now(),
+      "updated_at" timestamptz not null default now(),
+      "deleted_at" timestamptz null,
+      constraint "terminal_tracking_jobs_pkey" primary key ("id")
+    );`)
+    this.addSql(`create index if not exists "tt_jobs_org_tenant_idx" on "terminal_tracking_jobs" ("organization_id", "tenant_id");`)
+    this.addSql(`create index if not exists "tt_jobs_status_idx" on "terminal_tracking_jobs" ("status");`)
+    this.addSql(`create index if not exists "tt_jobs_next_poll_idx" on "terminal_tracking_jobs" ("next_poll_at");`)
+    this.addSql(`create index if not exists "tt_jobs_container_idx" on "terminal_tracking_jobs" ("container_number");`)
+
+    // ─── terminal_tracking_events ────────────────────────────
+    this.addSql(`create table if not exists "terminal_tracking_events" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "job_id" uuid not null,
+      "source" text not null default 'terminal',
+      "source_event_id" text not null,
+      "event_type" text not null,
+      "event_code" text not null,
+      "event_classifier_code" text null,
+      "event_date_time" timestamptz not null,
+      "container_number" text not null,
+      "ufv_gkey" text not null,
+      "transit_state" text null,
+      "visit_state" text null,
+      "facility_code" text null,
+      "facility_code_list_provider" text null,
+      "unlocode" varchar(5) null,
+      "visit_ref_in" text null,
+      "visit_ref_out" text null,
+      "vessel_name" text null,
+      "voyage_number" text null,
+      "mode_of_transport" text null,
+      "seals" jsonb null,
+      "vgm_weight_kg" double precision null,
+      "impediments" jsonb null,
+      "raw_data" jsonb null,
+      "created_at" timestamptz not null default now(),
+      constraint "terminal_tracking_events_pkey" primary key ("id")
+    );`)
+    this.addSql(`do $$ begin alter table "terminal_tracking_events"
+      add constraint "terminal_tracking_events_job_id_foreign"
+      foreign key ("job_id") references "terminal_tracking_jobs" ("id") on update cascade on delete cascade; exception when duplicate_object then null; when duplicate_table then null; end $$;`)
+    this.addSql(`create index if not exists "tt_events_org_tenant_idx" on "terminal_tracking_events" ("organization_id", "tenant_id");`)
+    this.addSql(`create index if not exists "tt_events_job_idx" on "terminal_tracking_events" ("job_id");`)
+    this.addSql(`create index if not exists "tt_events_container_idx" on "terminal_tracking_events" ("container_number");`)
+    this.addSql(`create index if not exists "tt_events_event_date_idx" on "terminal_tracking_events" ("event_date_time");`)
+    this.addSql(`create unique index if not exists "tt_events_source_event_uniq" on "terminal_tracking_events" ("job_id", "source", "source_event_id");`)
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`drop table if exists "terminal_tracking_events" cascade;`)
+    this.addSql(`drop table if exists "terminal_tracking_jobs" cascade;`)
+    this.addSql(`drop table if exists "terminal_tracking_terminal_configs" cascade;`)
+  }
+}

package/src/modules/terminal_tracking/migrations/Migration20260610120000_terminal_vessel_visits.ts

@@ -0,0 +1,40 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260610120000_terminal_vessel_visits extends Migration {
+  override async up(): Promise<void> {
+    // ─── terminal_tracking_vessel_visits ─────────────────────
+    this.addSql(`create table if not exists "terminal_tracking_vessel_visits" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "terminal_code" text not null,
+      "visit_ref" text not null,
+      "vessel_name" text null,
+      "ib_voyage" text null,
+      "ob_voyage" text null,
+      "line" text null,
+      "phase" text null,
+      "eta" timestamptz null,
+      "etd" timestamptz null,
+      "ata" timestamptz null,
+      "atd" timestamptz null,
+      "begin_receive" timestamptz null,
+      "dry_cutoff" timestamptz null,
+      "raw_data" jsonb null,
+      "created_at" timestamptz not null default now(),
+      "updated_at" timestamptz not null default now(),
+      constraint "terminal_tracking_vessel_visits_pkey" primary key ("id")
+    );`)
+    this.addSql(`create index if not exists "tt_vessel_visits_org_tenant_idx" on "terminal_tracking_vessel_visits" ("organization_id", "tenant_id");`)
+    this.addSql(`create index if not exists "tt_vessel_visits_visit_ref_idx" on "terminal_tracking_vessel_visits" ("visit_ref");`)
+    this.addSql(`create unique index if not exists "tt_vessel_visits_uniq" on "terminal_tracking_vessel_visits" ("organization_id", "tenant_id", "terminal_code", "visit_ref");`)
+
+    // ─── terminal_tracking_terminal_configs: vessel cache TTL ─
+    this.addSql(`alter table "terminal_tracking_terminal_configs" add column if not exists "vessel_cache_ttl_seconds" integer null;`)
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "terminal_tracking_terminal_configs" drop column if exists "vessel_cache_ttl_seconds";`)
+    this.addSql(`drop table if exists "terminal_tracking_vessel_visits" cascade;`)
+  }
+}

package/src/modules/terminal_tracking/migrations/Migration20260611120000_terminal_config_proxy.ts

@@ -0,0 +1,11 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260611120000_terminal_config_proxy extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(`alter table "terminal_tracking_terminal_configs" add column if not exists "proxy_url" text null;`)
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "terminal_tracking_terminal_configs" drop column if exists "proxy_url";`)
+  }
+}

package/src/modules/terminal_tracking/migrations/Migration20260707120000_terminal_job_availability_markers.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260707120000_terminal_job_availability_markers extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(`alter table "terminal_tracking_jobs" add column if not exists "empty_ready_at" timestamptz null;`)
+    this.addSql(`alter table "terminal_tracking_jobs" add column if not exists "holds_cleared_at" timestamptz null;`)
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "terminal_tracking_jobs" drop column if exists "empty_ready_at";`)
+    this.addSql(`alter table "terminal_tracking_jobs" drop column if exists "holds_cleared_at";`)
+  }
+}

package/src/modules/terminal_tracking/migrations/Migration20260805120000_terminal_event_loaded_at.ts

@@ -0,0 +1,16 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Additive-only: a nullable `loaded_at` timestamp on terminal_tracking_events.
+ * The N4 `Loaded` column parsed into a typed datetime, captured on every event
+ * regardless of the container's current transit state.
+ */
+export class Migration20260805120000_terminal_event_loaded_at extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(`alter table "terminal_tracking_events" add column if not exists "loaded_at" timestamptz null;`)
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "terminal_tracking_events" drop column if exists "loaded_at";`)
+  }
+}