@freighttech/terminal-tracking 0.7.0

package/dist/modules/terminal_tracking/i18n/es.json

@@ -0,0 +1,175 @@
+{
+  "terminal_tracking": {
+    "title": "Terminal Tracking",
+    "stops": {
+      "title": "Restricciones de carga",
+      "vsl": "Sin carga a buque",
+      "road": "Sin recogida por carretera",
+      "rail": "Sin recogida por ferrocarril"
+    },
+    "nav": {
+      "group": "Terminal Tracking",
+      "terminal_configs": "Terminals",
+      "tracking_jobs": "Tracked Containers"
+    },
+    "errors": {
+      "tenant_required": "Tenant context is required",
+      "organization_required": "Organization context is required"
+    },
+    "terminal_config": {
+      "title": "Terminal Configurations",
+      "displayName": "Name",
+      "terminalCode": "Terminal code",
+      "adapterType": "Adapter",
+      "baseUrl": "API base URL",
+      "proxyUrl": "URL de proxy de la API (opcional)",
+      "unlocode": "UN/LOCODE",
+      "isActive": "Active",
+      "gctHint": "Clave (base32) mostrada en el panel de GCT junto al código QR. A partir de ella se calcula un código de un solo uso en cada inicio de sesión."
+    },
+    "tracking_job": {
+      "title": "Terminal Tracking Jobs",
+      "containerNumber": "Container",
+      "status": "Status",
+      "lastPollAt": "Last polled",
+      "details": "Container Details",
+      "noEvents": "No terminal events yet. Use \"Poll now\" to fetch.",
+      "leg": "Facility visit",
+      "recentErrors": "Recent poll errors",
+      "jobInfo": "Tracking",
+      "nextPollAt": "Next poll",
+      "retryCount": "Retries",
+      "jobId": "Job ID",
+      "actions": {
+        "details": "Details",
+        "poll": "Poll now"
+      },
+      "flash": {
+        "polled": "Consultado — {n} nuevos, {u} actualizados evento(s)"
+      },
+      "statuses": {
+        "active": "Activo",
+        "paused": "Pausado",
+        "deactivated": "Desactivado",
+        "failed": "Fallido",
+        "completed": "Completado"
+      }
+    },
+    "event": {
+      "source_badge": "Terminal",
+      "yardPosition": "Yard position",
+      "vgm": "VGM (kg)",
+      "visitPhase": "Visit phase",
+      "impediments": "Holds",
+      "seals": "Seals",
+      "eta": "ETA",
+      "etd": "ETD",
+      "ata": "ATA",
+      "atd": "ATD",
+      "gate_in": "Gate In",
+      "yard": "In Yard / Discharged",
+      "loaded": "Loaded",
+      "loadedAt": "Cargado el",
+      "departed": "Departed",
+      "ufvGkey": "Ufv_Gkey",
+      "rawData": "Raw terminal data"
+    },
+    "holds": {
+      "unknown": {
+        "label": "Bloqueo desconocido",
+        "description": "Bloqueo de terminal no reconocido. Consulte los detalles con la terminal.",
+        "resolution": "Contacte con la terminal para determinar cómo se levanta este bloqueo."
+      },
+      "cfs_appointment": {
+        "label": "Cita CFS",
+        "description": "Se aplica mientras se acepta un pedido de importación del almacén CFS.",
+        "resolution": "Se elimina automáticamente al completar el pedido y el trabajo del almacén."
+      },
+      "customs_import_permission": {
+        "label": "Permiso aduanero (importación)",
+        "description": "Se aplica sistemáticamente a todos los contenedores de importación pendientes de despacho aduanero.",
+        "resolution": "Se elimina automáticamente tras actualizar el número MRN mediante los códigos PCS polacos."
+      },
+      "customs_import_hold": {
+        "label": "Retención aduanera (importación)",
+        "description": "Aplicada manualmente por un agente de aduanas para escaneo, inspección o por un problema de despacho.",
+        "resolution": "Solo un agente de aduanas puede levantarla — contacte con la oficina de aduanas."
+      },
+      "line_import_permission": {
+        "label": "Permiso de la naviera (importación)",
+        "description": "Se aplica sistemáticamente a todos los contenedores de importación hasta que la naviera los libera.",
+        "resolution": "Se elimina cuando la naviera libera el contenedor mediante su número PIN."
+      },
+      "oog_hold": {
+        "label": "Retención OOG",
+        "description": "Se aplica a contenedores de importación fuera de gálibo que requieren permisos especiales.",
+        "resolution": "Debe ser verificada por Baltic Hub antes de la recogida; hasta entonces el contenedor no puede avisarse para retirada."
+      },
+      "cfs_hold": {
+        "label": "Retención CFS",
+        "description": "Se aplica mientras se acepta un pedido de exportación del almacén CFS.",
+        "resolution": "Se elimina automáticamente al completar el pedido y el trabajo del almacén."
+      },
+      "customs_export_permission": {
+        "label": "Permiso aduanero (exportación)",
+        "description": "Se aplica sistemáticamente a los contenedores de exportación pendientes de despacho aduanero.",
+        "resolution": "Se elimina automáticamente tras la actualización del MRN; debe levantarse antes del plazo de despacho aduanero."
+      },
+      "customs_export_hold": {
+        "label": "Retención aduanera (exportación)",
+        "description": "Aplicada manualmente por un agente de aduanas para escaneo, inspección o por un problema de despacho.",
+        "resolution": "Solo un agente de aduanas puede levantarla — contacte con la oficina de aduanas."
+      },
+      "unit_vgm_load_permission": {
+        "label": "Permiso de carga VGM",
+        "description": "Se aplica a todos los contenedores de exportación llenos que aún no tienen masa bruta verificada.",
+        "resolution": "Se elimina cuando se carga el peso VGM en Navis."
+      },
+      "dgd_hold": {
+        "label": "Retención DGD",
+        "description": "Se aplica automáticamente a todos los contenedores de exportación con carga IMO (peligrosa).",
+        "resolution": "Requiere la presentación del documento DGD (declaración de mercancías peligrosas)."
+      },
+      "scanning_hold": {
+        "label": "Retención de escaneo",
+        "description": "Aplicada manualmente por un agente de aduanas; el contenedor debe presentarse para escaneo.",
+        "resolution": "La levanta aduanas tras el escaneo (selección DCT_CFS_SCANNING)."
+      },
+      "empty_permission": {
+        "label": "Permiso (vacío)",
+        "description": "Se aplica sistemáticamente a todos los contenedores vacíos pendientes de una referencia de liberación.",
+        "resolution": "Se elimina al proporcionar el número EDO / de reserva de la naviera."
+      },
+      "missing_agent_permission": {
+        "label": "Falta permiso del agente",
+        "description": "Relacionado con un pago PCS inactivo. Actualmente no bloquea la carga al buque ni la recogida.",
+        "resolution": "Se elimina introduciendo el código de la naviera en el campo Agent One."
+      },
+      "technical_full_container": {
+        "label": "Técnico (contenedor lleno)",
+        "description": "Se aplica a todos los contenedores llenos de importación/exportación para el reconocimiento de caracteres OCR. No bloquea el movimiento.",
+        "resolution": "No requiere acción — solo informativo."
+      },
+      "technical_live_reefer": {
+        "label": "Técnico (reefer activo)",
+        "description": "Se aplica a todos los contenedores reefer llenos para apoyar el OCR. No bloquea las operaciones.",
+        "resolution": "No requiere acción — solo informativo."
+      },
+      "terminal_hold": {
+        "label": "Retención de terminal",
+        "description": "Se aplica por una irregularidad del contenedor (etiquetado incorrecto, vigas dobladas, etc.).",
+        "resolution": "Contacte con el Servicio de Atención al Cliente de Baltic Hub."
+      },
+      "czrm_hold": {
+        "label": "Retención CZRM",
+        "description": "Aplicada por la oficina de aduanas.",
+        "resolution": "Contacte directamente con la oficina de aduanas para levantarla."
+      },
+      "izrx_hold": {
+        "label": "Retención IZRX",
+        "description": "Aplicada por la oficina de aduanas.",
+        "resolution": "Contacte directamente con la oficina de aduanas para levantarla."
+      }
+    }
+  }
+}

package/dist/modules/terminal_tracking/i18n/pl.json

@@ -0,0 +1,206 @@
+{
+  "terminal_tracking": {
+    "title": "Śledzenie terminali",
+    "stops": {
+      "title": "Ograniczenia załadunku",
+      "vsl": "Brak załadunku na statek",
+      "road": "Brak podjęcia drogowego",
+      "rail": "Brak podjęcia kolejowego"
+    },
+    "nav": {
+      "group": "Śledzenie terminali",
+      "terminal_configs": "Terminale",
+      "tracking_jobs": "Śledzone kontenery"
+    },
+    "errors": {
+      "tenant_required": "Wymagany jest kontekst najemcy",
+      "organization_required": "Wymagany jest kontekst organizacji"
+    },
+    "terminal_config": {
+      "title": "Konfiguracje terminali",
+      "displayName": "Nazwa",
+      "terminalCode": "Kod terminalu",
+      "adapterType": "Adapter",
+      "baseUrl": "Bazowy adres API",
+      "proxyUrl": "Adres proxy API (opcjonalnie)",
+      "unlocode": "UN/LOCODE",
+      "smdgCodes": "Kody SMDG (po przecinku)",
+      "bicCodes": "Kody BIC (po przecinku)",
+      "nameAliases": "Aliasy nazwy (po przecinku)",
+      "tokenUrl": "Adres URL tokenu",
+      "scope": "Zakres (scope)",
+      "clientId": "Identyfikator klienta",
+      "rateLimitRequests": "Limit zapytań",
+      "rateLimitWindowSeconds": "Okno (sekundy)",
+      "isActive": "Aktywny",
+      "unchanged": "bez zmian",
+      "credEditHint": "Pozostaw dane uwierzytelniające puste, aby ich nie zmieniać.",
+      "gctHint": "Klucz (base32) widoczny w panelu GCT obok kodu QR. Na jego podstawie przy każdym logowaniu obliczany jest aktualny kod jednorazowy.",
+      "section": {
+        "terminal": "Terminal",
+        "auth": "Uwierzytelnianie",
+        "matching": "Dopasowanie",
+        "advanced": "Zaawansowane"
+      },
+      "cred": {
+        "username": "Nazwa użytkownika",
+        "password": "Hasło",
+        "clientSecret": "Sekret klienta",
+        "companyCode": "Kod firmy",
+        "loginName": "Login",
+        "totpSecret": "Twój sekret 2FA"
+      },
+      "validation": {
+        "allCredentials": "Wprowadź wszystkie pola danych uwierzytelniających",
+        "credentialsRequired": "Dane uwierzytelniające są wymagane"
+      }
+    },
+    "tracking_job": {
+      "title": "Zadania śledzenia terminali",
+      "containerNumber": "Kontener",
+      "status": "Status",
+      "gateIn": "Wjazd",
+      "gateOut": "Wyjazd",
+      "holds": "Blokady",
+      "lastPollAt": "Ostatnie odpytanie",
+      "details": "Szczegóły kontenera",
+      "noEvents": "Brak zdarzeń terminalowych. Użyj „Odpytaj teraz”, aby pobrać.",
+      "leg": "Wizyta na terminalu",
+      "recentErrors": "Ostatnie błędy odpytania",
+      "jobInfo": "Śledzenie",
+      "nextPollAt": "Następne odpytanie",
+      "retryCount": "Ponowienia",
+      "jobId": "ID zadania",
+      "actions": {
+        "details": "Szczegóły",
+        "poll": "Odpytaj teraz"
+      },
+      "flash": {
+        "polled": "Odpytano — {n} nowych, {u} zaktualizowanych zdarzeń"
+      },
+      "statuses": {
+        "active": "Aktywny",
+        "paused": "Wstrzymany",
+        "deactivated": "Dezaktywowany",
+        "failed": "Błąd",
+        "completed": "Zakończony"
+      }
+    },
+    "event": {
+      "source_badge": "Terminal",
+      "yardPosition": "Pozycja na placu",
+      "vgm": "VGM (kg)",
+      "visitPhase": "Faza wizyty",
+      "impediments": "Blokady",
+      "seals": "Plomby",
+      "eta": "ETA",
+      "etd": "ETD",
+      "ata": "ATA",
+      "atd": "ATD",
+      "gate_in": "Wjazd (brama)",
+      "yard": "Na placu / rozładowany",
+      "loaded": "Załadowany",
+      "loadedAt": "Data załadunku",
+      "departed": "Wyjazd",
+      "ufvGkey": "Ufv_Gkey",
+      "rawData": "Surowe dane terminalu"
+    },
+    "holds": {
+      "unknown": {
+        "label": "Nieznana blokada",
+        "description": "Nierozpoznana blokada terminalowa. Szczegóły uzyskasz w terminalu.",
+        "resolution": "Skontaktuj się z terminalem, aby ustalić sposób zdjęcia blokady."
+      },
+      "cfs_appointment": {
+        "label": "Awizacja CFS",
+        "description": "Nakładana podczas przyjmowania zlecenia importowego przez magazyn CFS.",
+        "resolution": "Zdejmowana automatycznie po zrealizowaniu zlecenia i pracy magazynu."
+      },
+      "customs_import_permission": {
+        "label": "Pozwolenie celne (import)",
+        "description": "Nakładana systemowo na wszystkie kontenery importowe oczekujące na zwolnienie celne.",
+        "resolution": "Zdejmowana automatycznie po aktualizacji numeru MRN przy użyciu polskich kodów PCS."
+      },
+      "customs_import_hold": {
+        "label": "Blokada celna (import)",
+        "description": "Nakładana ręcznie przez funkcjonariusza celnego w celu skanowania, kontroli lub z powodu problemu z odprawą.",
+        "resolution": "Może ją zdjąć wyłącznie funkcjonariusz celny — skontaktuj się z urzędem celnym."
+      },
+      "line_import_permission": {
+        "label": "Pozwolenie armatora (import)",
+        "description": "Nakładana systemowo na wszystkie kontenery importowe do czasu zwolnienia przez armatora.",
+        "resolution": "Zdejmowana po zwolnieniu kontenera przez armatora numerem PIN."
+      },
+      "oog_hold": {
+        "label": "Blokada OOG",
+        "description": "Nakładana na ponadgabarytowe kontenery importowe wymagające specjalnych zezwoleń.",
+        "resolution": "Wymaga weryfikacji przez Baltic Hub przed odbiorem; do tego czasu kontener nie może zostać awizowany do odbioru."
+      },
+      "cfs_hold": {
+        "label": "Blokada CFS",
+        "description": "Nakładana podczas przyjmowania zlecenia eksportowego przez magazyn CFS.",
+        "resolution": "Zdejmowana automatycznie po zrealizowaniu zlecenia i pracy magazynu."
+      },
+      "customs_export_permission": {
+        "label": "Pozwolenie celne (eksport)",
+        "description": "Nakładana systemowo na kontenery eksportowe oczekujące na zwolnienie celne.",
+        "resolution": "Zdejmowana automatycznie po aktualizacji MRN; musi zostać zdjęta przed terminem odprawy celnej."
+      },
+      "customs_export_hold": {
+        "label": "Blokada celna (eksport)",
+        "description": "Nakładana ręcznie przez funkcjonariusza celnego w celu skanowania, kontroli lub z powodu problemu z odprawą.",
+        "resolution": "Może ją zdjąć wyłącznie funkcjonariusz celny — skontaktuj się z urzędem celnym."
+      },
+      "unit_vgm_load_permission": {
+        "label": "Pozwolenie VGM na załadunek",
+        "description": "Nakładana na wszystkie pełne kontenery eksportowe bez zweryfikowanej masy brutto (VGM).",
+        "resolution": "Zdejmowana po wprowadzeniu masy VGM do systemu Navis."
+      },
+      "dgd_hold": {
+        "label": "Blokada DGD",
+        "description": "Nakładana automatycznie na wszystkie kontenery eksportowe z ładunkiem IMO (niebezpiecznym).",
+        "resolution": "Wymaga złożenia dokumentu DGD (deklaracji ładunku niebezpiecznego)."
+      },
+      "scanning_hold": {
+        "label": "Blokada skanowania",
+        "description": "Nakładana ręcznie przez funkcjonariusza celnego; kontener musi zostać przedstawiony do skanowania.",
+        "resolution": "Zdejmowana przez służby celne po skanowaniu (wybór DCT_CFS_SCANNING)."
+      },
+      "empty_permission": {
+        "label": "Pozwolenie (pusty)",
+        "description": "Nakładana systemowo na wszystkie puste kontenery oczekujące na referencję zwolnienia.",
+        "resolution": "Zdejmowana po podaniu numeru EDO / bookingu od armatora."
+      },
+      "missing_agent_permission": {
+        "label": "Brak pozwolenia agenta",
+        "description": "Dotyczy nieaktywnej płatności PCS. Obecnie nie blokuje załadunku na statek ani odbioru.",
+        "resolution": "Zdejmowana po wpisaniu kodu armatora w polu Agent One."
+      },
+      "technical_full_container": {
+        "label": "Techniczna (pełny kontener)",
+        "description": "Nakładana na wszystkie pełne kontenery importowe/eksportowe w celu obsługi rozpoznawania znaków OCR. Nie blokuje ruchu.",
+        "resolution": "Nie wymaga działań — wyłącznie informacyjna."
+      },
+      "technical_live_reefer": {
+        "label": "Techniczna (aktywny reefer)",
+        "description": "Nakładana na wszystkie pełne kontenery chłodnicze w celu obsługi OCR. Nie blokuje operacji.",
+        "resolution": "Nie wymaga działań — wyłącznie informacyjna."
+      },
+      "terminal_hold": {
+        "label": "Blokada terminalowa",
+        "description": "Nakładana z powodu nieprawidłowości kontenera (błędne oznakowanie, wygięte belki kontenera itp.).",
+        "resolution": "Skontaktuj się z Biurem Obsługi Klienta Baltic Hub."
+      },
+      "czrm_hold": {
+        "label": "Blokada CZRM",
+        "description": "Nakładana przez urząd celny.",
+        "resolution": "Skontaktuj się bezpośrednio z urzędem celnym w celu jej zdjęcia."
+      },
+      "izrx_hold": {
+        "label": "Blokada IZRX",
+        "description": "Nakładana przez urząd celny.",
+        "resolution": "Skontaktuj się bezpośrednio z urzędem celnym w celu jej zdjęcia."
+      }
+    }
+  }
+}

package/dist/modules/terminal_tracking/index.js

@@ -0,0 +1,15 @@
+import "./commands/index.js";
+const metadata = {
+  name: "terminal_tracking",
+  title: "Terminal Tracking",
+  version: "0.1.0",
+  description: "Container terminal (Navis N4) tracking with per-terminal config, periodic polling, and events.",
+  author: "FreightTech",
+  license: "Proprietary"
+};
+import { features } from "./acl.js";
+export {
+  features,
+  metadata
+};
+//# sourceMappingURL=index.js.map

package/dist/modules/terminal_tracking/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/terminal_tracking/index.ts"],
+  "sourcesContent": ["import type { ModuleInfo } from '@open-mercato/shared/modules/registry'\nimport './commands'\n\nexport const metadata: ModuleInfo = {\n  name: 'terminal_tracking',\n  title: 'Terminal Tracking',\n  version: '0.1.0',\n  description: 'Container terminal (Navis N4) tracking with per-terminal config, periodic polling, and events.',\n  author: 'FreightTech',\n  license: 'Proprietary',\n}\n\nexport { features } from './acl'\n"],
+  "mappings": "AACA,OAAO;AAEA,MAAM,WAAuB;AAAA,EAClC,MAAM;AAAA,EACN,OAAO;AAAA,EACP,SAAS;AAAA,EACT,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,SAAS;AACX;AAEA,SAAS,gBAAgB;",
+  "names": []
+}

package/dist/modules/terminal_tracking/lib/adapters/bct/adapter.js

@@ -0,0 +1,164 @@
+import { basicAuthHeader, BctAuthError } from "./auth/basic.js";
+import { mapContainerToEvents, normalizeIncosVesselVisit, splitVisitRef } from "./incos-semantics.js";
+import { n4Request } from "../n4/http.js";
+import { terminalLogger } from "../../logger.js";
+function joinUrl(base, path) {
+  return `${base.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+}
+class BctTerminalAdapter {
+  constructor() {
+    this.adapterType = "bct";
+    this.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"
+    };
+  }
+  containerUrl(containerNumber, config) {
+    const path = config.endpoints?.unit?.trim() || this.defaultEndpoints.unit;
+    return `${joinUrl(config.baseUrl, path)}/${encodeURIComponent(containerNumber)}`;
+  }
+  vesselUrl(vesselCode, voyage, config) {
+    const path = config.endpoints?.vessel?.trim() || this.defaultEndpoints.vessel;
+    return `${joinUrl(config.baseUrl, path)}/${encodeURIComponent(vesselCode)}/${encodeURIComponent(voyage)}`;
+  }
+  async getContainer(containerNumber, config) {
+    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;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error(`INCOS container response was not valid JSON for ${config.terminalCode}`);
+    }
+    if (String(parsed.status ?? "").toUpperCase() !== "SUCCESS") return null;
+    const data = parsed.data;
+    if (!data || !data.container_nbr) return null;
+    return data;
+  }
+  async fetchEvents(input) {
+    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) {
+    const { containerNumbers, config } = input;
+    if (containerNumbers.length === 0) return { events: [] };
+    const events = [];
+    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) {
+    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;
+    try {
+      parsed = JSON.parse(text);
+    } 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) {
+    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}) \u2014 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 };
+    }
+  }
+}
+export {
+  BctTerminalAdapter
+};
+//# sourceMappingURL=adapter.js.map

package/dist/modules/terminal_tracking/lib/adapters/bct/adapter.js.map

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

package/dist/modules/terminal_tracking/lib/adapters/bct/auth/basic.js

@@ -0,0 +1,23 @@
+class BctAuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BctAuthError";
+  }
+}
+function basicAuthHeader(config) {
+  const auth = config.authConfig ?? {};
+  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}`;
+}
+export {
+  BctAuthError,
+  basicAuthHeader
+};
+//# sourceMappingURL=basic.js.map

package/dist/modules/terminal_tracking/lib/adapters/bct/auth/basic.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../src/modules/terminal_tracking/lib/adapters/bct/auth/basic.ts"],
+  "sourcesContent": ["import type { ResolvedTerminalConfig } from '../../../terminal-adapter'\n\n/**\n * INCOS authenticates every call with plain HTTP Basic (`-u user:password` in\n * the vendor docs). There is no token endpoint or cache \u2014 the header is derived\n * from the decrypted `auth_config` on each request. Credentials live in\n * `auth_config` as `{ username, password }` (encrypted at rest; see\n * encryption.ts).\n */\n\nexport class BctAuthError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = 'BctAuthError'\n  }\n}\n\n/**\n * Build the `Authorization: Basic <base64(user:pass)>` header for a config.\n * Throws `BctAuthError` when either credential is missing, so a misconfigured\n * terminal fails with a clear message rather than a silent 401.\n */\nexport function basicAuthHeader(config: ResolvedTerminalConfig): string {\n  const auth = (config.authConfig ?? {}) as Record<string, unknown>\n  const username = String(auth.username ?? '')\n  const password = String(auth.password ?? '')\n  if (!username || !password) {\n    throw new BctAuthError(\n      `BCT/INCOS config ${config.terminalCode} is missing username/password in auth_config`,\n    )\n  }\n  const token = Buffer.from(`${username}:${password}`, 'utf8').toString('base64')\n  return `Basic ${token}`\n}\n"],
+  "mappings": "AAUO,MAAM,qBAAqB,MAAM;AAAA,EACtC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAOO,SAAS,gBAAgB,QAAwC;AACtE,QAAM,OAAQ,OAAO,cAAc,CAAC;AACpC,QAAM,WAAW,OAAO,KAAK,YAAY,EAAE;AAC3C,QAAM,WAAW,OAAO,KAAK,YAAY,EAAE;AAC3C,MAAI,CAAC,YAAY,CAAC,UAAU;AAC1B,UAAM,IAAI;AAAA,MACR,oBAAoB,OAAO,YAAY;AAAA,IACzC;AAAA,EACF;AACA,QAAM,QAAQ,OAAO,KAAK,GAAG,QAAQ,IAAI,QAAQ,IAAI,MAAM,EAAE,SAAS,QAAQ;AAC9E,SAAO,SAAS,KAAK;AACvB;",
+  "names": []
+}