@freighttech/terminal-tracking 0.7.0

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

@@ -0,0 +1,119 @@
+/**
+ * Availability detection for terminal containers.
+ *
+ * Derives two business signals from the latest N4 `/unit` snapshot of a
+ * container, reusing the hold catalogue in `./holds` to decide what actually
+ * blocks a physical pickup:
+ *
+ * - **Empty-ready** — an empty container sitting in the yard with no
+ *   movement-blocking holds is releasable for collection. Per Baltic Hub's
+ *   Navis docs, `EMPTY PERMISSION` is applied to *every* empty regardless of
+ *   direction and is cleared once the carrier's EDO/booking is provided; empties
+ *   are handled under N4 category `Storage`, not `Export` — so this does not
+ *   gate on category.
+ * - **Import holds-cleared** — an import container in the yard whose blocking
+ *   holds have just been lifted (transition blocked → clear) has become
+ *   collectable.
+ *
+ * Pure helpers — no DI, no persistence. The service owns the one-shot guard
+ * (job-level `emptyReadyAt` / `holdsClearedAt`).
+ */
+import { resolveHolds } from './holds'
+import { parseTerminalStops } from './stops'
+
+/** N4 in-yard transit state (discharged, available on the terminal). */
+const YARD_STATE = 'S40_YARD'
+
+/** Minimal shape both a fetched event and a persisted `TerminalEvent` satisfy. */
+export type AvailabilityInput = {
+  transitState?: string | null
+  impediments?: string[] | null
+  rawData?: Record<string, unknown> | null
+}
+
+/** Count holds that block physical movement / loading / pickup. */
+export function blockingHoldCount(impediments: readonly string[] | null | undefined): number {
+  return resolveHolds(impediments ?? null).filter((h) => h.blocksMovement).length
+}
+
+/**
+ * Whether two raw impediment lists differ as sets (order- and duplicate-
+ * insensitive, whitespace-trimmed). An absent/null prior is treated as empty,
+ * so a first-seen container carrying holds counts as a change. Drives the
+ * `equipment.holds_updated` event (fires on every poll the hold set changes).
+ */
+export function impedimentsChanged(
+  prior: readonly string[] | null | undefined,
+  current: readonly string[] | null | undefined,
+): boolean {
+  const norm = (l: readonly string[] | null | undefined): string[] =>
+    Array.from(new Set((l ?? []).map((c) => c.trim()).filter((c) => c !== ''))).sort()
+  const a = norm(prior)
+  const b = norm(current)
+  if (a.length !== b.length) return true
+  return a.some((code, i) => code !== b[i])
+}
+
+/** N4 `Category` column, normalized to import/export (null if absent/unknown). */
+function category(e: AvailabilityInput): 'import' | 'export' | null {
+  const c = String(e.rawData?.['Category'] ?? '').trim().toLowerCase()
+  return c === 'import' || c === 'export' ? c : null
+}
+
+/**
+ * Whether the container is empty, per the N4 `Frght Kind` column. Baltic Hub
+ * reports empties as `Empty` (confirmed against a real /unit payload, 2026-07);
+ * `MTY` is kept as a defensive alias for other N4 terminals. Full containers
+ * report `FCL`/`LCL`.
+ */
+function isEmpty(e: AvailabilityInput): boolean {
+  const kind = String(e.rawData?.['Frght Kind'] ?? '').trim().toUpperCase()
+  return kind === 'EMPTY' || kind === 'MTY'
+}
+
+function isInYard(e: AvailabilityInput): boolean {
+  return e.transitState === YARD_STATE
+}
+
+/**
+ * Whether the terminal has explicitly stopped road pickup for this container
+ * (Stop-Road). Only an *explicit* stop counts — an absent column (`null`, the
+ * pre-update world) or a `false` never blocks, keeping this purely additive.
+ *
+ * This gates only the **state-based** `isEmptyReady` below, where a road stop
+ * simply *delays* the one-shot until it lifts (the signal is re-evaluated every
+ * poll). The **transition-based** `isImportHoldsCleared` is deliberately NOT
+ * gated: it fires on the holds blocked→clear edge, so suppressing it during a
+ * road stop would lose the event entirely once the edge has passed, rather than
+ * defer it — the container's holds still genuinely cleared.
+ */
+function isRoadPickupStopped(e: AvailabilityInput): boolean {
+  return parseTerminalStops(e.rawData).road === true
+}
+
+/**
+ * Empty ready for pickup: an empty container in the yard with no movement-
+ * blocking holds (its `EMPTY PERMISSION` and any others have cleared). State-
+ * based — evaluate on the latest snapshot. Direction-agnostic, since empties
+ * sit under N4 category `Storage` rather than `Export`.
+ */
+export function isEmptyReady(e: AvailabilityInput): boolean {
+  return isEmpty(e) && isInYard(e) && blockingHoldCount(e.impediments) === 0 && !isRoadPickupStopped(e)
+}
+
+/**
+ * Import holds cleared: an import container in the yard whose blocking holds
+ * went from present → none this poll. Transition-based, so it never fires for a
+ * container that was never blocked.
+ */
+export function isImportHoldsCleared(
+  e: AvailabilityInput,
+  priorImpediments: readonly string[] | null | undefined,
+): boolean {
+  return (
+    category(e) === 'import' &&
+    isInYard(e) &&
+    blockingHoldCount(priorImpediments) > 0 &&
+    blockingHoldCount(e.impediments) === 0
+  )
+}

package/src/modules/terminal_tracking/lib/ensure-schedule.ts

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto'
+import { terminalLogger } from './logger'
+
+type SchedulerLike = {
+  register: (registration: Record<string, unknown>) => Promise<void>
+  exists?: (scheduleId: string) => Promise<boolean>
+}
+
+type ResolveLike = { resolve: <T = unknown>(name: string) => T }
+
+/**
+ * Deterministic RFC 4122 (v5-style) uuid derived from a stable seed, so the same
+ * (org, tenant) always maps to the same scheduled-job id. The scheduler upserts
+ * by id (idempotent `register`), and consumers validate with `z.uuid()`, so the
+ * version (nibble 13 = '5') and variant (nibble 17 = 8-b) bits must be set.
+ */
+function deterministicUuid(seed: string): string {
+  const hex = createHash('sha1').update(seed).digest('hex').slice(0, 32).split('')
+  hex[12] = '5' // version 5
+  hex[16] = ((parseInt(hex[16], 16) & 0x3) | 0x8).toString(16) // variant 10xx -> 8..b
+  const s = hex.join('')
+  return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`
+}
+
+/**
+ * Ensure the periodic "poll all" schedule exists for an org/tenant — create-only.
+ *
+ * The schedule is seeded with the module defaults the first time only. Once it
+ * exists, this no-ops so user edits in the scheduler settings (cadence, enabled
+ * state) are the source of truth and are never overwritten — `setup.ts` and the
+ * config/job-save callers re-run this purely to self-heal orgs that predate the
+ * module. Stays a single row thanks to the deterministic id. No-ops gracefully
+ * when the optional scheduler module isn't installed.
+ */
+export async function ensureTerminalPollSchedule(
+  container: ResolveLike,
+  scope: { organizationId: string; tenantId: string },
+): Promise<void> {
+  let scheduler: SchedulerLike
+  try {
+    scheduler = container.resolve<SchedulerLike>('schedulerService')
+  } catch {
+    return // scheduler module not installed
+  }
+  if (!scheduler?.register) return
+
+  const id = deterministicUuid(`terminal_tracking:poll_all:${scope.organizationId}:${scope.tenantId}`)
+
+  // Create-only: never overwrite an existing schedule, so UI cadence/enabled edits win.
+  // (`register` is a full upsert, so without this guard every config/job save would
+  // revert the row to the defaults below.)
+  try {
+    if (scheduler.exists && (await scheduler.exists(id))) return
+  } catch {
+    // Existence check is best-effort; fall through to register on failure.
+  }
+
+  try {
+    await scheduler.register({
+      id,
+      name: 'Terminal Tracking Poll',
+      description:
+        'Polls all active terminal tracking jobs every 4 hours. Change the cadence in the scheduler settings.',
+      scopeType: 'organization',
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      scheduleType: 'cron',
+      scheduleValue: '0 */4 * * *',
+      timezone: 'UTC',
+      targetType: 'command',
+      targetCommand: 'terminal_tracking.tracking.poll_all',
+      targetPayload: { tenantId: scope.tenantId, organizationId: scope.organizationId },
+      sourceType: 'module',
+      sourceModule: 'terminal_tracking',
+      isEnabled: true,
+    })
+  } catch (err) {
+    terminalLogger.warn('Failed to ensure terminal poll schedule', {
+      organizationId: scope.organizationId,
+      message: err instanceof Error ? err.message : String(err),
+    })
+  }
+}

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

@@ -0,0 +1,344 @@
+/**
+ * Unit-impediment ("hold") catalogue for Navis N4 terminals (Baltic Hub / BCT).
+ *
+ * N4 returns the `Unit Impediments` column as a comma-separated list of codes,
+ * each prefixed with `!` and delimited inconsistently — some use underscores
+ * (`!TECHNICAL_FULL_CONTAINER`), others spaces (`!CUSTOMS EXPORT PERMISSION`).
+ * This module normalizes a raw code and resolves it to a human explanation plus
+ * a severity, so the UI can render a coloured badge with an informative tooltip.
+ *
+ * Source of truth for the catalogue: Baltic Hub documentation
+ * https://baltichub.com/dla-klienta/navis
+ *
+ * Pure helper — no DI, no i18n, no React. English strings by convention; the
+ * consuming component owns localization/colour mapping.
+ */
+
+/**
+ * How urgently a hold needs attention.
+ * - `critical`: blocks movement/load/pickup and typically needs a third party
+ *   (customs office, terminal CS) to lift — cannot be self-served.
+ * - `warning`: routine, systematic permission that is auto- or self-removed in
+ *   the normal flow (MRN update, VGM upload, line PIN) but currently blocks.
+ * - `info`: technical/administrative marker that does NOT block operations.
+ */
+export type HoldSeverity = 'critical' | 'warning' | 'info'
+
+/** Which container flow the hold belongs to. */
+export type HoldCategory = 'import' | 'export' | 'general'
+
+export type HoldDefinition = {
+  /** Canonical, normalized code (no `!`, spaced, upper-case). */
+  code: string
+  /** Short human label for the badge. */
+  label: string
+  category: HoldCategory
+  severity: HoldSeverity
+  /** Whether the hold blocks physical movement / loading / pickup. */
+  blocksMovement: boolean
+  /** What the hold means / why it is applied. */
+  description: string
+  /** How the hold is cleared and by whom. */
+  resolution: string
+}
+
+/** Resolved hold: a known definition, or an `unknown: true` fallback. */
+export type HoldInfo = HoldDefinition & {
+  /** Original code as received from the terminal (with `!`, original spacing). */
+  rawCode: string
+  /** True when the code was not in the catalogue. */
+  unknown: boolean
+  /**
+   * Stable slug for i18n lookup, e.g. `dgd_hold`. The `label`/`description`/
+   * `resolution` fields above are English fallbacks; the consuming component
+   * resolves `terminal_tracking.holds.<i18nKey>.{label,description,resolution}`
+   * against the active locale, falling back to those English strings.
+   */
+  i18nKey: string
+}
+
+/** Derive the i18n slug for a normalized hold code (e.g. `DGD HOLD` → `dgd_hold`). */
+export function holdI18nKey(normalizedCode: string): string {
+  return normalizedCode.toLowerCase().replace(/ /g, '_')
+}
+
+/** Sort/threshold rank: higher = more urgent. */
+export const HOLD_SEVERITY_RANK: Record<HoldSeverity, number> = {
+  critical: 3,
+  warning: 2,
+  info: 1,
+}
+
+/**
+ * Normalize a raw N4 impediment code into its canonical lookup key: drop the
+ * leading `!`, trim, upper-case, and collapse runs of `_`/whitespace into a
+ * single space so `TECHNICAL_FULL_CONTAINER` and `TECHNICAL FULL CONTAINER`
+ * resolve to the same entry.
+ */
+export function normalizeHoldCode(rawCode: string): string {
+  return rawCode
+    .replace(/^!/, '')
+    .replace(/[_\s]+/g, ' ')
+    .trim()
+    .toUpperCase()
+}
+
+function def(
+  code: string,
+  category: HoldCategory,
+  severity: HoldSeverity,
+  blocksMovement: boolean,
+  label: string,
+  description: string,
+  resolution: string,
+): HoldDefinition {
+  return { code, category, severity, blocksMovement, label, description, resolution }
+}
+
+/** Catalogue keyed by normalized code. */
+const HOLD_CATALOGUE: Record<string, HoldDefinition> = {
+  // ── Import ────────────────────────────────────────────────────────────────
+  'CFS APPOINTMENT': def(
+    'CFS APPOINTMENT',
+    'import',
+    'warning',
+    true,
+    'CFS appointment',
+    'Applied while a CFS (warehouse) import order is being accepted.',
+    'Cleared automatically once the order is completed and warehouse work is done.',
+  ),
+  'CUSTOMS IMPORT PERMISSION': def(
+    'CUSTOMS IMPORT PERMISSION',
+    'import',
+    'warning',
+    true,
+    'Customs import permission',
+    'Applied systematically to every import container pending customs release.',
+    'Removed automatically after the MRN number is updated via the Polish PCS codes.',
+  ),
+  'CUSTOMS IMPORT HOLD': def(
+    'CUSTOMS IMPORT HOLD',
+    'import',
+    'critical',
+    true,
+    'Customs import hold',
+    'Placed manually by a customs officer for scanning, inspection or a clearance issue.',
+    'Only a customs officer can lift it — contact the customs office.',
+  ),
+  'LINE IMPORT PERMISSION': def(
+    'LINE IMPORT PERMISSION',
+    'import',
+    'warning',
+    true,
+    'Line import permission',
+    'Applied systematically to every import container until the shipping line releases it.',
+    'Removed once the line releases the container via its PIN number.',
+  ),
+  'OOG HOLD': def(
+    'OOG HOLD',
+    'import',
+    'critical',
+    true,
+    'OOG hold',
+    'Applied to out-of-gauge import containers that require special handling permits.',
+    'Must be verified by Baltic Hub before pickup; the container cannot be notified for collection until then.',
+  ),
+
+  // ── Export ────────────────────────────────────────────────────────────────
+  'CFS HOLD': def(
+    'CFS HOLD',
+    'export',
+    'warning',
+    true,
+    'CFS hold',
+    'Applied while a CFS (warehouse) export order is being accepted.',
+    'Cleared automatically once the order is completed and warehouse work is done.',
+  ),
+  'CUSTOMS EXPORT PERMISSION': def(
+    'CUSTOMS EXPORT PERMISSION',
+    'export',
+    'warning',
+    true,
+    'Customs export permission',
+    'Applied systematically to export containers pending customs release.',
+    'Removed automatically after the MRN update; must be cleared before the customs-clearance deadline.',
+  ),
+  'CUSTOMS EXPORT HOLD': def(
+    'CUSTOMS EXPORT HOLD',
+    'export',
+    'critical',
+    true,
+    'Customs export hold',
+    'Placed manually by a customs officer for scanning, inspection or a clearance issue.',
+    'Only a customs officer can lift it — contact the customs office.',
+  ),
+  'UNIT VGM LOAD PERMISSION': def(
+    'UNIT VGM LOAD PERMISSION',
+    'export',
+    'warning',
+    true,
+    'VGM load permission',
+    'Applied to every full export container that has no verified gross mass yet.',
+    'Removed when the VGM weight is uploaded to Navis.',
+  ),
+  'DGD HOLD': def(
+    'DGD HOLD',
+    'export',
+    'critical',
+    true,
+    'DGD hold',
+    'Applied automatically to every export container carrying IMO (dangerous) cargo.',
+    'Requires the DGD (dangerous-goods declaration) document to be submitted.',
+  ),
+  'SCANNING HOLD': def(
+    'SCANNING HOLD',
+    'export',
+    'critical',
+    true,
+    'Scanning hold',
+    'Placed manually by a customs officer; the container must be presented for scanning.',
+    'Cleared by customs after scanning (DCT_CFS_SCANNING selection).',
+  ),
+
+  // ── General / technical ─────────────────────────────────────────────────────
+  'EMPTY PERMISSION': def(
+    'EMPTY PERMISSION',
+    'general',
+    'warning',
+    true,
+    'Empty permission',
+    'Applied systematically to every empty container pending a release reference.',
+    'Removed once the EDO / booking number from the shipping line is provided.',
+  ),
+  'MISSING AGENT PERMISSION': def(
+    'MISSING AGENT PERMISSION',
+    'general',
+    'info',
+    false,
+    'Missing agent permission',
+    'Relates to an inactive PCS payment. Does not currently block ship loading or pickup.',
+    'Removed by entering the shipping code in the Agent One field.',
+  ),
+  'TECHNICAL FULL CONTAINER': def(
+    'TECHNICAL FULL CONTAINER',
+    'general',
+    'info',
+    false,
+    'Technical (full container)',
+    'Applied to every full import/export container to support OCR character recognition. Does not block movement.',
+    'No action required — informational only.',
+  ),
+  'TECHNICAL LIVE REEFER': def(
+    'TECHNICAL LIVE REEFER',
+    'general',
+    'info',
+    false,
+    'Technical (live reefer)',
+    'Applied to every full reefer container to support OCR. Does not block operations.',
+    'No action required — informational only.',
+  ),
+  // Baltic Hub's Navis docs spell this "REFFER" (double F); keep both spellings
+  // so the real terminal code resolves to the non-blocking definition instead of
+  // the blocking unknown-hold fallback.
+  'TECHNICAL LIVE REFFER': def(
+    'TECHNICAL LIVE REFFER',
+    'general',
+    'info',
+    false,
+    'Technical (live reefer)',
+    'Applied to every full reefer container to support OCR. Does not block operations.',
+    'No action required — informational only.',
+  ),
+  'TERMINAL HOLD': def(
+    'TERMINAL HOLD',
+    'general',
+    'critical',
+    true,
+    'Terminal hold',
+    'Applied for a container irregularity (incorrect labelling, bent container beams, etc.).',
+    'Contact Baltic Hub Customer Service to resolve.',
+  ),
+  'CZRM HOLD': def(
+    'CZRM HOLD',
+    'general',
+    'critical',
+    true,
+    'CZRM hold',
+    'Applied by the customs office.',
+    'Contact the customs office directly to have it lifted.',
+  ),
+  'IZRX HOLD': def(
+    'IZRX HOLD',
+    'general',
+    'critical',
+    true,
+    'IZRX hold',
+    'Applied by the customs office.',
+    'Contact the customs office directly to have it lifted.',
+  ),
+}
+
+/**
+ * The canonical, normalized codes known to the catalogue, sorted by severity
+ * (most-urgent first) then alphabetically. Consumers that offer a constrained
+ * "pick a hold" UI (dropdown) or validate manual entry against the known set
+ * use this instead of hard-coding the list.
+ */
+export const HOLD_CODES: string[] = Object.keys(HOLD_CATALOGUE).sort((a, b) => {
+  const bySeverity = HOLD_SEVERITY_RANK[HOLD_CATALOGUE[b].severity] - HOLD_SEVERITY_RANK[HOLD_CATALOGUE[a].severity]
+  return bySeverity !== 0 ? bySeverity : a.localeCompare(b)
+})
+
+/** True when `code` (normalized) is a known catalogue entry. */
+export function isKnownHoldCode(code: string): boolean {
+  return Object.prototype.hasOwnProperty.call(HOLD_CATALOGUE, normalizeHoldCode(code))
+}
+
+/**
+ * Resolve a single raw impediment code to its explanation + severity. Unknown
+ * codes return a `warning`-severity fallback that echoes the cleaned code, so a
+ * never-before-seen hold still renders something meaningful and visible.
+ */
+export function getHoldInfo(rawCode: string): HoldInfo {
+  const key = normalizeHoldCode(rawCode)
+  const found = HOLD_CATALOGUE[key]
+  if (found) {
+    return { ...found, rawCode, unknown: false, i18nKey: holdI18nKey(key) }
+  }
+  // Unknown code: surface the raw hold itself as the label (just drop the `!`
+  // marker) so an operator still sees exactly what the terminal reported.
+  const rawLabel = rawCode.replace(/^!/, '').trim()
+  return {
+    code: key,
+    label: rawLabel || 'Unknown hold',
+    category: 'general',
+    severity: 'warning',
+    blocksMovement: true,
+    description: 'Unrecognised terminal hold. Refer to the terminal for details.',
+    resolution: 'Contact the terminal to determine how this hold is cleared.',
+    rawCode,
+    unknown: true,
+    i18nKey: 'unknown',
+  }
+}
+
+/**
+ * Resolve a list of raw impediment codes, sorted most-urgent first. Empty,
+ * null, or all-whitespace entries are dropped.
+ */
+export function resolveHolds(rawCodes: readonly string[] | null | undefined): HoldInfo[] {
+  if (!rawCodes || rawCodes.length === 0) return []
+  return rawCodes
+    .filter((c) => c != null && c.trim() !== '')
+    .map(getHoldInfo)
+    .sort((a, b) => HOLD_SEVERITY_RANK[b.severity] - HOLD_SEVERITY_RANK[a.severity])
+}
+
+/** The highest severity among a list of raw codes, or `null` when there are none. */
+export function highestHoldSeverity(
+  rawCodes: readonly string[] | null | undefined,
+): HoldSeverity | null {
+  const holds = resolveHolds(rawCodes)
+  if (holds.length === 0) return null
+  return holds[0].severity // already sorted most-urgent first
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Thin logging wrapper. Mirrors the shipment-tracking logger shape but stays
+ * dependency-light (falls back to console). The host app's logger can be wired
+ * in later via DI if needed.
+ */
+const PREFIX = '[terminal-tracking]'
+
+export const terminalLogger = {
+  debug(message: string, meta?: Record<string, unknown>) {
+    if (process.env.TERMINAL_TRACKING_DEBUG) console.debug(PREFIX, message, meta ?? '')
+  },
+  info(message: string, meta?: Record<string, unknown>) {
+    console.log(PREFIX, message, meta ?? '')
+  },
+  warn(message: string, meta?: Record<string, unknown>) {
+    console.warn(PREFIX, message, meta ?? '')
+  },
+  error(message: string, meta?: Record<string, unknown>) {
+    console.error(PREFIX, message, meta ?? '')
+  },
+}

package/src/modules/terminal_tracking/lib/rate-limiter.ts

@@ -0,0 +1,52 @@
+import { terminalLogger } from './logger'
+
+export type RateLimitResult = {
+  allowed: boolean
+  retryAfterSeconds?: number
+}
+
+export type CacheService = {
+  get(key: string): Promise<string | null>
+  set(key: string, value: string, ttlSeconds?: number): Promise<void>
+}
+
+/**
+ * Token-bucket rate limiter backed by a cache.
+ * Key: `tt:ratelimit:{tenantId}:{terminalCode}`
+ */
+export async function checkRateLimit(
+  cache: CacheService,
+  tenantId: string,
+  terminalCode: string,
+  maxRequests: number,
+  windowSeconds: number,
+): Promise<RateLimitResult> {
+  const key = `tt:ratelimit:${tenantId}:${terminalCode}`
+  const now = Date.now()
+
+  const raw = await cache.get(key)
+  let tokens = maxRequests
+  let lastRefill = now
+
+  if (raw) {
+    try {
+      const state = JSON.parse(raw) as { tokens: number; lastRefill: number }
+      const elapsed = (now - state.lastRefill) / 1000
+      const refilled = Math.floor((elapsed / windowSeconds) * maxRequests)
+      tokens = Math.min(maxRequests, state.tokens + refilled)
+      lastRefill = refilled > 0 ? now : state.lastRefill
+    } catch {
+      // Corrupted cache entry, reset
+    }
+  }
+
+  if (tokens <= 0) {
+    const retryAfterSeconds = Math.ceil(windowSeconds / maxRequests)
+    terminalLogger.debug('Rate limited', { terminalCode, tenantId, retryAfterSeconds })
+    return { allowed: false, retryAfterSeconds }
+  }
+
+  tokens -= 1
+  await cache.set(key, JSON.stringify({ tokens, lastRefill }), windowSeconds * 2)
+  return { allowed: true }
+}