@freighttech/shipment-tracking 0.6.0

package/dist/modules/shipment_tracking/lib/poi-types.js

@@ -0,0 +1,43 @@
+const PROXIMITY_EVENT_CODES = {
+  PORT_ARRIVAL: "PARR",
+  PORT_PROXIMITY_ARRIVAL: "PPRA",
+  PORT_PROXIMITY_DEPARTURE: "PPRD",
+  TERMINAL_ARRIVAL: "TARR",
+  TERMINAL_PROXIMITY_ARRIVAL: "TPRA",
+  TERMINAL_PROXIMITY_DEPARTURE: "TPRD",
+  WAYPOINT_REACHED: "WAYR"
+};
+const PROXIMITY_EVENT_CATEGORY = {
+  PORT_ARRIVAL: "arrival",
+  PORT_PROXIMITY_ARRIVAL: "proximity",
+  PORT_PROXIMITY_DEPARTURE: "departure",
+  TERMINAL_ARRIVAL: "arrival",
+  TERMINAL_PROXIMITY_ARRIVAL: "proximity",
+  TERMINAL_PROXIMITY_DEPARTURE: "departure",
+  WAYPOINT_REACHED: "waypoint"
+};
+const PROXIMITY_EVENT_TO_STRING = {
+  PORT_ARRIVAL: "port_arrival",
+  PORT_PROXIMITY_ARRIVAL: "port_proximity_arrival",
+  PORT_PROXIMITY_DEPARTURE: "port_departure",
+  TERMINAL_ARRIVAL: "terminal_arrival",
+  TERMINAL_PROXIMITY_ARRIVAL: "terminal_proximity_arrival",
+  TERMINAL_PROXIMITY_DEPARTURE: "terminal_departure",
+  WAYPOINT_REACHED: "waypoint_reached"
+};
+function getJobPoiEventId(eventType) {
+  const typeString = PROXIMITY_EVENT_TO_STRING[eventType];
+  return `shipment_tracking.tracking_job.poi.${typeString}`;
+}
+function getShipmentPoiEventId(eventType) {
+  const typeString = PROXIMITY_EVENT_TO_STRING[eventType];
+  return `shipment_tracking.poi.${typeString}`;
+}
+export {
+  PROXIMITY_EVENT_CATEGORY,
+  PROXIMITY_EVENT_CODES,
+  PROXIMITY_EVENT_TO_STRING,
+  getJobPoiEventId,
+  getShipmentPoiEventId
+};
+//# sourceMappingURL=poi-types.js.map

package/dist/modules/shipment_tracking/lib/poi-types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/poi-types.ts"],
+  "sourcesContent": ["/**\n * POI Proximity Event Types\n *\n * Type definitions for AIS POI proximity events received from the\n * poi-proximity-detector service via NATS.\n */\n\n// \u2500\u2500\u2500 Enums \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Types of proximity events emitted by the POI detector.\n */\nexport type ProximityEventType =\n  | 'PORT_ARRIVAL'\n  | 'PORT_PROXIMITY_ARRIVAL'\n  | 'PORT_PROXIMITY_DEPARTURE'\n  | 'TERMINAL_ARRIVAL'\n  | 'TERMINAL_PROXIMITY_ARRIVAL'\n  | 'TERMINAL_PROXIMITY_DEPARTURE'\n  | 'WAYPOINT_REACHED'\n\n/**\n * Map POI event types to distinct event codes for TrackingEvent records.\n * These codes are AIS-specific and don't conflict with standard DCSA codes.\n * Labels are resolved via i18n: shipment_tracking.event_codes.<CODE>\n */\nexport const PROXIMITY_EVENT_CODES: Record<ProximityEventType, string> = {\n  PORT_ARRIVAL: 'PARR',\n  PORT_PROXIMITY_ARRIVAL: 'PPRA',\n  PORT_PROXIMITY_DEPARTURE: 'PPRD',\n  TERMINAL_ARRIVAL: 'TARR',\n  TERMINAL_PROXIMITY_ARRIVAL: 'TPRA',\n  TERMINAL_PROXIMITY_DEPARTURE: 'TPRD',\n  WAYPOINT_REACHED: 'WAYR',\n}\n\n/**\n * Categorize events as arrival, departure, or proximity.\n */\nexport type ProximityEventCategory = 'arrival' | 'departure' | 'proximity' | 'waypoint'\n\nexport const PROXIMITY_EVENT_CATEGORY: Record<ProximityEventType, ProximityEventCategory> = {\n  PORT_ARRIVAL: 'arrival',\n  PORT_PROXIMITY_ARRIVAL: 'proximity',\n  PORT_PROXIMITY_DEPARTURE: 'departure',\n  TERMINAL_ARRIVAL: 'arrival',\n  TERMINAL_PROXIMITY_ARRIVAL: 'proximity',\n  TERMINAL_PROXIMITY_DEPARTURE: 'departure',\n  WAYPOINT_REACHED: 'waypoint',\n}\n\n// \u2500\u2500\u2500 Event Payload \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * POI proximity event payload received from the AIS POI detector.\n *\n * This matches the ShipPoiProximityData interface from the poi-proximity-detector service.\n */\nexport interface PoiProximityEvent {\n  /**\n   * Vessel IMO number. In the AIS system `ships.id` IS the IMO, and the detector\n   * sets this field from `ship.id` \u2014 so this is the real IMO, not an internal id.\n   * Used to match shipments directly by `vesselImo` (no MMSI\u2192IMO lookup).\n   */\n  shipId: number\n\n  /** Ship name */\n  shipName: string\n\n  /** Maritime Mobile Service Identity (9 digits) */\n  mmsi: number\n\n  /** Latitude of ship position */\n  lat: number\n\n  /** Longitude of ship position */\n  lng: number\n\n  /** Actual Time of Arrival (ISO 8601) - present for arrival events */\n  ata?: string\n\n  /** Actual Time of Departure (ISO 8601) - present for departure events */\n  atd?: string\n\n  /** Type of proximity event */\n  type: ProximityEventType\n\n  /** POI code for arrival events (e.g., port/terminal LOCODE or custom code) */\n  arrivedPoiCode?: string\n\n  /** POI code for departure events */\n  departedPoiCode?: string\n\n  /** Distance to POI in meters (null if not applicable) */\n  distanceToPoiMeters: number | null\n\n  /** Sequence order for multiple events in same message batch */\n  sequenceOrder: number\n\n  /**\n   * Human-friendly POI identity for arrival/proximity events at a matched port or terminal.\n   * All nullable \u2014 which fields are populated depends on the event type and how rich the\n   * matched POI is (e.g. a PORT_ARRIVAL from a port's geometric center may only have `city`).\n   * Resolved for display via {@link resolvePoiLocationName}.\n   */\n  portName?: string | null\n  terminalName?: string | null\n  city?: string | null\n\n  /**\n   * Human-friendly region name in Polish (e.g. \"Morze P\u00F3\u0142nocne\"), set for open-water\n   * WAYPOINT_REACHED events that have no port/terminal/city. Null for port/terminal events.\n   */\n  regionNamePl?: string | null\n\n  /** Human-friendly region name in English (e.g. \"North Sea\"). Null for port/terminal events \u2014 see {@link regionNamePl}. */\n  regionNameEn?: string | null\n}\n\n// \u2500\u2500\u2500 Processed Event \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Processed POI event enriched with shipment context.\n */\nexport interface ProcessedPoiEvent {\n  /** Original POI event */\n  poiEvent: PoiProximityEvent\n\n  /** IMO number (resolved from MMSI if needed) */\n  vesselImo: string | null\n\n  /** Matched shipment IDs */\n  shipmentIds: string[]\n\n  /** Event timestamp (from ata/atd or current time) */\n  eventDateTime: Date\n\n  /** POI code (arrived or departed) */\n  poiCode: string | null\n\n  /** Mapped event code for TrackingEvent */\n  eventCode: string\n\n  /** Source event ID for deduplication */\n  sourceEventId: string\n}\n\n// \u2500\u2500\u2500 Event ID Mapping \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * POI event type string used in event IDs.\n * Maps ProximityEventType to the underscore-separated format used in event declarations.\n */\nexport type PoiEventTypeString =\n  | 'port_arrival'\n  | 'port_proximity_arrival'\n  | 'port_departure'\n  | 'terminal_arrival'\n  | 'terminal_proximity_arrival'\n  | 'terminal_departure'\n  | 'waypoint_reached'\n\n/**\n * Map ProximityEventType to the event type string used in event IDs.\n */\nexport const PROXIMITY_EVENT_TO_STRING: Record<ProximityEventType, PoiEventTypeString> = {\n  PORT_ARRIVAL: 'port_arrival',\n  PORT_PROXIMITY_ARRIVAL: 'port_proximity_arrival',\n  PORT_PROXIMITY_DEPARTURE: 'port_departure',\n  TERMINAL_ARRIVAL: 'terminal_arrival',\n  TERMINAL_PROXIMITY_ARRIVAL: 'terminal_proximity_arrival',\n  TERMINAL_PROXIMITY_DEPARTURE: 'terminal_departure',\n  WAYPOINT_REACHED: 'waypoint_reached',\n}\n\n/**\n * Get the per-tracking-job event ID for a POI event type.\n * Used for notifications to avoid duplicates for multi-container bookings.\n *\n * @example\n * getJobPoiEventId('PORT_ARRIVAL') // 'shipment_tracking.tracking_job.poi.port_arrival'\n */\nexport function getJobPoiEventId(eventType: ProximityEventType): string {\n  const typeString = PROXIMITY_EVENT_TO_STRING[eventType]\n  return `shipment_tracking.tracking_job.poi.${typeString}`\n}\n\n/**\n * Get the per-shipment event ID for a POI event type.\n * Used for webhooks and external integrations.\n *\n * @example\n * getShipmentPoiEventId('PORT_ARRIVAL') // 'shipment_tracking.poi.port_arrival'\n */\nexport function getShipmentPoiEventId(eventType: ProximityEventType): string {\n  const typeString = PROXIMITY_EVENT_TO_STRING[eventType]\n  return `shipment_tracking.poi.${typeString}`\n}\n"],
+  "mappings": "AA0BO,MAAM,wBAA4D;AAAA,EACvE,cAAc;AAAA,EACd,wBAAwB;AAAA,EACxB,0BAA0B;AAAA,EAC1B,kBAAkB;AAAA,EAClB,4BAA4B;AAAA,EAC5B,8BAA8B;AAAA,EAC9B,kBAAkB;AACpB;AAOO,MAAM,2BAA+E;AAAA,EAC1F,cAAc;AAAA,EACd,wBAAwB;AAAA,EACxB,0BAA0B;AAAA,EAC1B,kBAAkB;AAAA,EAClB,4BAA4B;AAAA,EAC5B,8BAA8B;AAAA,EAC9B,kBAAkB;AACpB;AAoHO,MAAM,4BAA4E;AAAA,EACvF,cAAc;AAAA,EACd,wBAAwB;AAAA,EACxB,0BAA0B;AAAA,EAC1B,kBAAkB;AAAA,EAClB,4BAA4B;AAAA,EAC5B,8BAA8B;AAAA,EAC9B,kBAAkB;AACpB;AASO,SAAS,iBAAiB,WAAuC;AACtE,QAAM,aAAa,0BAA0B,SAAS;AACtD,SAAO,sCAAsC,UAAU;AACzD;AASO,SAAS,sBAAsB,WAAuC;AAC3E,QAAM,aAAa,0BAA0B,SAAS;AACtD,SAAO,yBAAyB,UAAU;AAC5C;",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/rate-limiter.js

@@ -0,0 +1,31 @@
+import { logRateLimit } from "./logger.js";
+async function checkRateLimit(cache, tenantId, carrierCode, maxRequests, windowSeconds) {
+  const key = `st:ratelimit:${tenantId}:${carrierCode}`;
+  const now = Date.now();
+  const raw = await cache.get(key);
+  let tokens = maxRequests;
+  let lastRefill = now;
+  if (raw) {
+    try {
+      const state = JSON.parse(raw);
+      const elapsed = (now - state.lastRefill) / 1e3;
+      const refilled = Math.floor(elapsed / windowSeconds * maxRequests);
+      tokens = Math.min(maxRequests, state.tokens + refilled);
+      lastRefill = refilled > 0 ? now : state.lastRefill;
+    } catch {
+    }
+  }
+  if (tokens <= 0) {
+    const retryAfterSeconds = Math.ceil(windowSeconds / maxRequests);
+    logRateLimit({ carrierCode, tenantId, allowed: false, retryAfterSeconds });
+    return { allowed: false, retryAfterSeconds };
+  }
+  tokens -= 1;
+  await cache.set(key, JSON.stringify({ tokens, lastRefill }), windowSeconds * 2);
+  logRateLimit({ carrierCode, tenantId, allowed: true });
+  return { allowed: true };
+}
+export {
+  checkRateLimit
+};
+//# sourceMappingURL=rate-limiter.js.map

package/dist/modules/shipment_tracking/lib/rate-limiter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/rate-limiter.ts"],
+  "sourcesContent": ["import { logRateLimit } from './logger'\n\nexport type RateLimitResult = {\n  allowed: boolean\n  retryAfterSeconds?: number\n}\n\nexport type CacheService = {\n  get(key: string): Promise<string | null>\n  set(key: string, value: string, ttlSeconds?: number): Promise<void>\n}\n\n/**\n * Token bucket rate limiter using a cache backend.\n *\n * Key: `st:ratelimit:{tenantId}:{carrier}`\n *\n * Stores the current token count and last refill timestamp in the cache.\n * Refills tokens proportionally based on elapsed time.\n */\nexport async function checkRateLimit(\n  cache: CacheService,\n  tenantId: string,\n  carrierCode: string,\n  maxRequests: number,\n  windowSeconds: number,\n): Promise<RateLimitResult> {\n  const key = `st:ratelimit:${tenantId}:${carrierCode}`\n  const now = Date.now()\n\n  const raw = await cache.get(key)\n  let tokens = maxRequests\n  let lastRefill = now\n\n  if (raw) {\n    try {\n      const state = JSON.parse(raw) as { tokens: number; lastRefill: number }\n      const elapsed = (now - state.lastRefill) / 1000\n      const refilled = Math.floor((elapsed / windowSeconds) * maxRequests)\n      tokens = Math.min(maxRequests, state.tokens + refilled)\n      lastRefill = refilled > 0 ? now : state.lastRefill\n    } catch {\n      // Corrupted cache entry, reset\n    }\n  }\n\n  if (tokens <= 0) {\n    const retryAfterSeconds = Math.ceil(windowSeconds / maxRequests)\n    logRateLimit({ carrierCode, tenantId, allowed: false, retryAfterSeconds })\n    return { allowed: false, retryAfterSeconds }\n  }\n\n  tokens -= 1\n  await cache.set(key, JSON.stringify({ tokens, lastRefill }), windowSeconds * 2)\n\n  logRateLimit({ carrierCode, tenantId, allowed: true })\n  return { allowed: true }\n}\n"],
+  "mappings": "AAAA,SAAS,oBAAoB;AAoB7B,eAAsB,eACpB,OACA,UACA,aACA,aACA,eAC0B;AAC1B,QAAM,MAAM,gBAAgB,QAAQ,IAAI,WAAW;AACnD,QAAM,MAAM,KAAK,IAAI;AAErB,QAAM,MAAM,MAAM,MAAM,IAAI,GAAG;AAC/B,MAAI,SAAS;AACb,MAAI,aAAa;AAEjB,MAAI,KAAK;AACP,QAAI;AACF,YAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,YAAM,WAAW,MAAM,MAAM,cAAc;AAC3C,YAAM,WAAW,KAAK,MAAO,UAAU,gBAAiB,WAAW;AACnE,eAAS,KAAK,IAAI,aAAa,MAAM,SAAS,QAAQ;AACtD,mBAAa,WAAW,IAAI,MAAM,MAAM;AAAA,IAC1C,QAAQ;AAAA,IAER;AAAA,EACF;AAEA,MAAI,UAAU,GAAG;AACf,UAAM,oBAAoB,KAAK,KAAK,gBAAgB,WAAW;AAC/D,iBAAa,EAAE,aAAa,UAAU,SAAS,OAAO,kBAAkB,CAAC;AACzE,WAAO,EAAE,SAAS,OAAO,kBAAkB;AAAA,EAC7C;AAEA,YAAU;AACV,QAAM,MAAM,IAAI,KAAK,KAAK,UAAU,EAAE,QAAQ,WAAW,CAAC,GAAG,gBAAgB,CAAC;AAE9E,eAAa,EAAE,aAAa,UAAU,SAAS,KAAK,CAAC;AACrD,SAAO,EAAE,SAAS,KAAK;AACzB;",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/route-extraction.js

@@ -0,0 +1,187 @@
+const ROUTE_DETAIL_EXCLUDED_EVENT_CODES = /* @__PURE__ */ new Set(["WAYR", "TARR", "TPRA", "TPRD"]);
+function earliestIso(a, b) {
+  if (!a) return b ?? null;
+  if (!b) return a;
+  return a < b ? a : b;
+}
+function latestIso(a, b) {
+  if (!a) return b ?? null;
+  if (!b) return a;
+  return a > b ? a : b;
+}
+function extractRouteFromEvents(events, context) {
+  if (!events || events.length === 0) {
+    return [];
+  }
+  const sortedEvents = [...events].sort(
+    (a, b) => new Date(a.eventDateTime).getTime() - new Date(b.eventDateTime).getTime()
+  );
+  const locationMap = /* @__PURE__ */ new Map();
+  for (const event of sortedEvents) {
+    if (ROUTE_DETAIL_EXCLUDED_EVENT_CODES.has(event.eventCode)) continue;
+    const loc = event.locationUnlocode || event.locationName;
+    if (!loc) continue;
+    if (!locationMap.has(loc)) {
+      const countryCode = event.locationUnlocode?.length === 5 ? event.locationUnlocode.slice(0, 2) : null;
+      locationMap.set(loc, {
+        name: event.locationName || loc,
+        unlocode: event.locationUnlocode || null,
+        countryCode,
+        vessels: /* @__PURE__ */ new Map(),
+        isTransshipment: false,
+        // Initialize facility fields
+        facilityCode: null,
+        facilityCodeListProvider: null,
+        facilityTypeCode: null,
+        facilityAddress: null,
+        coords: null
+      });
+    }
+    const entry = locationMap.get(loc);
+    if (event.facilityCode && !entry.facilityCode) {
+      entry.facilityCode = event.facilityCode;
+      entry.facilityCodeListProvider = event.facilityCodeListProvider || null;
+    }
+    if (event.facilityTypeCode && !entry.facilityTypeCode) {
+      entry.facilityTypeCode = event.facilityTypeCode;
+    }
+    if (event.facilityAddress && !entry.facilityAddress) {
+      entry.facilityAddress = event.facilityAddress;
+    }
+    if (event.latitude != null && event.longitude != null && !entry.coords) {
+      entry.coords = { latitude: event.latitude, longitude: event.longitude };
+    }
+    if (event.vesselName) {
+      const existingImo = entry.vessels.get(event.vesselName);
+      if (!existingImo && event.vesselImo) {
+        entry.vessels.set(event.vesselName, event.vesselImo);
+      } else if (!entry.vessels.has(event.vesselName)) {
+        entry.vessels.set(event.vesselName, event.vesselImo || null);
+      }
+    }
+    if (event.eventCode === "ARRI" && event.eventClassifierCode === "ACT") {
+      entry.ata = event.eventDateTime;
+    }
+    if (event.eventCode === "GTIN" && event.eventClassifierCode === "ACT" && !entry.ata) {
+      if (event.facilityTypeCode === "POTE" || event.facilityTypeCode === "INTE") {
+        entry.ata = event.eventDateTime;
+      }
+    }
+    if (event.eventCode === "DEPA" && event.eventClassifierCode === "ACT") {
+      entry.atd = event.eventDateTime;
+    }
+    if (event.eventCode === "GTOT" && event.eventClassifierCode === "ACT" && !entry.atd) {
+      entry.atd = event.eventDateTime;
+    }
+    if ((event.eventCode === "PARR" || event.eventCode === "PPRA") && event.eventClassifierCode === "ACT" && !entry.ata) {
+      entry.ata = event.eventDateTime;
+    }
+    if (event.eventCode === "PPRD" && event.eventClassifierCode === "ACT" && !entry.atd) {
+      entry.atd = event.eventDateTime;
+    }
+    if (event.eventCode === "ARRI" && (event.eventClassifierCode === "PLN" || event.eventClassifierCode === "EST")) {
+      if (!entry.eta) entry.eta = event.eventDateTime;
+    }
+    if (event.eventCode === "DEPA" && (event.eventClassifierCode === "PLN" || event.eventClassifierCode === "EST")) {
+      if (!entry.etd) entry.etd = event.eventDateTime;
+    }
+    if (event.isTransshipmentMove || (event.eventCode === "DISC" || event.eventCode === "LOAD")) {
+      entry.isTransshipment = true;
+    }
+  }
+  const stops = [];
+  const locations = Array.from(locationMap.entries());
+  for (let i = 0; i < locations.length; i++) {
+    const [key, data] = locations[i];
+    const isFirst = i === 0;
+    const isLast = i === locations.length - 1;
+    let type = data.isTransshipment ? "transshipment" : "port_call";
+    if (isFirst || key === context?.originUnlocode) {
+      type = "origin";
+    } else if (isLast || key === context?.destinationUnlocode) {
+      type = "destination";
+    }
+    const vesselEntries = Array.from(data.vessels.entries());
+    const lastVessel = vesselEntries.length > 0 ? vesselEntries[vesselEntries.length - 1] : null;
+    const vesselName = lastVessel ? lastVessel[0] : null;
+    const vesselImo = lastVessel ? lastVessel[1] : null;
+    stops.push({
+      location: data.name,
+      unlocode: data.unlocode,
+      type,
+      vesselName,
+      vesselImo,
+      ata: data.ata || null,
+      atd: data.atd || null,
+      eta: data.eta || null,
+      etd: data.etd || null,
+      // Facility details
+      countryCode: data.countryCode || null,
+      facilityCode: data.facilityCode || null,
+      facilityCodeListProvider: data.facilityCodeListProvider || null,
+      facilityTypeCode: data.facilityTypeCode || null,
+      facilityAddress: data.facilityAddress || null,
+      coords: data.coords || null,
+      operatorName: null
+      // Will be populated by BIC enrichment if needed
+    });
+  }
+  const merged = [];
+  for (const stop of stops) {
+    const prev = merged[merged.length - 1];
+    if (prev && prev.location === stop.location) {
+      prev.ata = earliestIso(prev.ata, stop.ata);
+      prev.atd = latestIso(prev.atd, stop.atd);
+      prev.eta = earliestIso(prev.eta, stop.eta);
+      prev.etd = latestIso(prev.etd, stop.etd);
+      prev.vesselName = prev.vesselName ?? stop.vesselName;
+      prev.vesselImo = prev.vesselImo ?? stop.vesselImo;
+      if (prev.unlocode?.length !== 5 && stop.unlocode?.length === 5) prev.unlocode = stop.unlocode;
+      prev.countryCode = prev.countryCode ?? stop.countryCode;
+      prev.facilityCode = prev.facilityCode ?? stop.facilityCode;
+      prev.facilityCodeListProvider = prev.facilityCodeListProvider ?? stop.facilityCodeListProvider;
+      prev.facilityTypeCode = prev.facilityTypeCode ?? stop.facilityTypeCode;
+      prev.facilityAddress = prev.facilityAddress ?? stop.facilityAddress;
+      prev.coords = prev.coords ?? stop.coords;
+      if (stop.type === "origin") prev.type = "origin";
+      else if (stop.type === "destination" && prev.type !== "origin") prev.type = "destination";
+      else if (stop.type === "transshipment" && prev.type === "port_call") prev.type = "transshipment";
+      continue;
+    }
+    merged.push({ ...stop });
+  }
+  return merged;
+}
+function mapTrackingEventToEntry(event) {
+  return {
+    id: event.id,
+    eventType: event.eventType,
+    eventCode: event.eventCode,
+    eventClassifierCode: event.eventClassifierCode,
+    eventDateTime: event.eventDateTime.toISOString(),
+    description: event.description || null,
+    locationName: event.locationName || null,
+    locationUnlocode: event.locationUnlocode || null,
+    regionNamePl: event.regionNamePl || null,
+    regionNameEn: event.regionNameEn || null,
+    vesselName: event.vesselName || null,
+    vesselImo: event.vesselImo || null,
+    voyageNumber: event.voyageNumber || null,
+    isTransshipmentMove: event.isTransshipmentMove ?? null,
+    emptyIndicatorCode: event.emptyIndicatorCode ?? null,
+    // Facility fields
+    facilityCode: event.facilityCode || null,
+    facilityCodeListProvider: event.facilityCodeListProvider || null,
+    facilityTypeCode: event.facilityTypeCode || null,
+    facilityAddress: event.facilityAddress || null,
+    latitude: event.latitude ?? null,
+    longitude: event.longitude ?? null,
+    // Seal fields
+    seals: event.seals ?? null
+  };
+}
+export {
+  extractRouteFromEvents,
+  mapTrackingEventToEntry
+};
+//# sourceMappingURL=route-extraction.js.map

package/dist/modules/shipment_tracking/lib/route-extraction.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/route-extraction.ts"],
+  "sourcesContent": ["/**\n * Route extraction utilities for shipment tracking.\n * \n * Extracts route stops from tracking events for display in the shipment details drawer.\n * This logic is shared between:\n * - TrackingService (when populating denormalized data on shipment)\n * - ShipmentDetailsDrawer (as types reference)\n */\n\n// \u2500\u2500\u2500 Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Seal information for a container.\n */\nexport interface SealInfo {\n  number: string\n  source?: string | null  // CAR (carrier), SHI (shipper), TER (terminal), CUS (customs)\n  type?: string | null\n}\n\n/**\n * A stop along the shipment's route (origin, transshipment, or destination).\n * Stored as JSONB on the Shipment entity.\n * \n * Includes facility/terminal details from DCSA events for rich location display.\n */\nexport interface RouteStopEntry {\n  // Core fields\n  location: string                     // Terminal or port name\n  unlocode?: string | null             // UN/LOCODE (e.g., \"PLGDN\")\n  // 'transshipment' = cargo changes vessels here; 'port_call' = same vessel calls en route\n  type: 'origin' | 'transshipment' | 'port_call' | 'destination'\n  vesselName?: string | null           // Vessel name for this leg\n  vesselImo?: string | null            // Vessel IMO number for vessel tracking\n  \n  // Timestamps\n  ata?: string | null                  // Actual arrival - ISO datetime string\n  atd?: string | null                  // Actual departure - ISO datetime string\n  eta?: string | null                  // Estimated arrival - ISO datetime string (for delay calculation)\n  etd?: string | null                  // Estimated departure - ISO datetime string (for delay calculation)\n  \n  // Facility/terminal details (from DCSA events)\n  countryCode?: string | null          // ISO 3166-1 alpha-2 (e.g., \"PL\")\n  facilityCode?: string | null         // SMDG/BIC code (e.g., \"DCT\")\n  facilityCodeListProvider?: 'BIC' | 'SMDG' | null\n  facilityTypeCode?: string | null     // POTE (port terminal), DEPO (depot), etc.\n  facilityAddress?: string | null      // Full address string from DCSA otherFacility\n  coords?: {\n    latitude: number\n    longitude: number\n  } | null\n  \n  // From BIC enrichment (optional)\n  operatorName?: string | null\n}\n\n/**\n * A cargo/tracking event entry for a specific container.\n * Stored as JSONB on the Shipment entity.\n * \n * Includes facility details from DCSA events for route extraction.\n */\nexport interface CargoEventEntry {\n  // Core fields\n  id: string\n  eventType: string\n  eventCode: string\n  eventClassifierCode?: 'ACT' | 'PLN' | 'EST' | null\n  eventDateTime: string                // ISO datetime string\n  description?: string | null\n  \n  // Location fields\n  locationName?: string | null\n  locationUnlocode?: string | null\n\n  // Human-friendly region names for AIS POI events (localized at render). Null for carrier events.\n  regionNamePl?: string | null\n  regionNameEn?: string | null\n\n  // Vessel/voyage fields\n  vesselName?: string | null\n  vesselImo?: string | null\n  voyageNumber?: string | null\n  isTransshipmentMove?: boolean | null\n  \n  emptyIndicatorCode?: 'EMPTY' | 'LADEN' | null\n\n  // Facility/terminal details (from DCSA events)\n  facilityCode?: string | null         // SMDG/BIC code (e.g., \"DCT\")\n  facilityCodeListProvider?: 'BIC' | 'SMDG' | null\n  facilityTypeCode?: string | null     // POTE, DEPO, etc.\n  facilityAddress?: string | null      // Full address string\n  latitude?: number | null\n  longitude?: number | null\n  \n  // Seal information (from DCSA events)\n  seals?: SealInfo[] | null\n}\n\n/**\n * Context for route extraction - provides origin/destination hints.\n */\nexport interface RouteExtractionContext {\n  originUnlocode?: string | null\n  destinationUnlocode?: string | null\n}\n\n// \u2500\u2500\u2500 Route Extraction \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * AIS POI event codes that are too fine-grained for Route Details and are\n * skipped during route extraction:\n * - WAYR (waypoint reached) \u2014 open-water grid codes (e.g. \"N051E001-00773\"), no real place\n * - TARR / TPRA / TPRD (terminal arrival / proximity arrival / proximity departure)\n *\n * Port-level AIS events (PARR/PPRA/PPRD) and all carrier/DCSA milestones\n * (ARRI/DEPA/GTIN/GTOT/LOAD/DISC, \u2026) are kept \u2014 they define the route.\n * Excluded events remain in the Journey Timeline (cargoEvents).\n */\nconst ROUTE_DETAIL_EXCLUDED_EVENT_CODES = new Set(['WAYR', 'TARR', 'TPRA', 'TPRD'])\n\n// ISO datetime strings are UTC (toISOString), so lexicographic compare == chronological.\nfunction earliestIso(a?: string | null, b?: string | null): string | null {\n  if (!a) return b ?? null\n  if (!b) return a\n  return a < b ? a : b\n}\nfunction latestIso(a?: string | null, b?: string | null): string | null {\n  if (!a) return b ?? null\n  if (!b) return a\n  return a > b ? a : b\n}\n\n/**\n * Extracts route stops from a list of cargo events.\n * \n * The algorithm:\n * 1. Sorts events chronologically\n * 2. Groups events by location (unlocode or name)\n * 3. Tracks vessels, arrival/departure times, and transshipment indicators\n * 4. Assigns type (origin/transshipment/destination) based on position and context\n * \n * @param events - Array of cargo events (already filtered for specific container)\n * @param context - Optional context with origin/destination hints\n * @returns Array of route stops in chronological order\n */\nexport function extractRouteFromEvents(\n  events: CargoEventEntry[],\n  context?: RouteExtractionContext\n): RouteStopEntry[] {\n  if (!events || events.length === 0) {\n    return []\n  }\n\n  // Sort events by datetime\n  const sortedEvents = [...events].sort(\n    (a, b) => new Date(a.eventDateTime).getTime() - new Date(b.eventDateTime).getTime()\n  )\n\n  // Build location map with timestamps and facility data\n  // vessels is a Map of vesselName -> vesselImo (to track IMO alongside name)\n  const locationMap = new Map<string, {\n    name: string\n    unlocode?: string | null\n    countryCode?: string | null\n    vessels: Map<string, string | null>  // vesselName -> vesselImo\n    ata?: string\n    atd?: string\n    eta?: string\n    etd?: string\n    isTransshipment: boolean\n    // Facility data from events\n    facilityCode?: string | null\n    facilityCodeListProvider?: 'BIC' | 'SMDG' | null\n    facilityTypeCode?: string | null\n    facilityAddress?: string | null\n    coords?: { latitude: number; longitude: number } | null\n  }>()\n\n  for (const event of sortedEvents) {\n    // Skip fine-grained AIS POI events (waypoints + terminals) \u2014 Route Details\n    // shows port-level stops only. See ROUTE_DETAIL_EXCLUDED_EVENT_CODES.\n    if (ROUTE_DETAIL_EXCLUDED_EVENT_CODES.has(event.eventCode)) continue\n\n    const loc = event.locationUnlocode || event.locationName\n    if (!loc) continue\n\n    if (!locationMap.has(loc)) {\n      // Extract country code from UN/LOCODE (first 2 chars)\n      const countryCode = event.locationUnlocode?.length === 5\n        ? event.locationUnlocode.slice(0, 2)\n        : null\n\n      locationMap.set(loc, {\n        name: event.locationName || loc,\n        unlocode: event.locationUnlocode || null,\n        countryCode,\n        vessels: new Map<string, string | null>(),\n        isTransshipment: false,\n        // Initialize facility fields\n        facilityCode: null,\n        facilityCodeListProvider: null,\n        facilityTypeCode: null,\n        facilityAddress: null,\n        coords: null,\n      })\n    }\n\n    const entry = locationMap.get(loc)!\n\n    // Update facility data if this event has more complete info\n    // Prefer events with facility codes over those without\n    if (event.facilityCode && !entry.facilityCode) {\n      entry.facilityCode = event.facilityCode\n      entry.facilityCodeListProvider = event.facilityCodeListProvider || null\n    }\n    if (event.facilityTypeCode && !entry.facilityTypeCode) {\n      entry.facilityTypeCode = event.facilityTypeCode\n    }\n    if (event.facilityAddress && !entry.facilityAddress) {\n      entry.facilityAddress = event.facilityAddress\n    }\n    if (event.latitude != null && event.longitude != null && !entry.coords) {\n      entry.coords = { latitude: event.latitude, longitude: event.longitude }\n    }\n\n    if (event.vesselName) {\n      // Store vessel name with its IMO (may be null)\n      // If we already have this vessel, only update if the new event has an IMO\n      const existingImo = entry.vessels.get(event.vesselName)\n      if (!existingImo && event.vesselImo) {\n        entry.vessels.set(event.vesselName, event.vesselImo)\n      } else if (!entry.vessels.has(event.vesselName)) {\n        entry.vessels.set(event.vesselName, event.vesselImo || null)\n      }\n    }\n\n    // Track actual arrivals/departures\n    // ARRI = vessel arrival at port\n    // GTIN = gate-in (container enters terminal via truck/rail - indicates arrival for inland segments)\n    // For the first segment (depot to port), GTIN at the port indicates the container arrived there\n    if (event.eventCode === 'ARRI' && event.eventClassifierCode === 'ACT') {\n      entry.ata = event.eventDateTime\n    }\n    // Use GTIN as arrival indicator for port terminals when no ARRI event exists\n    // This handles the depot-to-port segment where container arrives by truck\n    if (event.eventCode === 'GTIN' && event.eventClassifierCode === 'ACT' && !entry.ata) {\n      // Only use GTIN as arrival if it's at a port terminal (POTE) or intermodal (INTE)\n      if (event.facilityTypeCode === 'POTE' || event.facilityTypeCode === 'INTE') {\n        entry.ata = event.eventDateTime\n      }\n    }\n    if (event.eventCode === 'DEPA' && event.eventClassifierCode === 'ACT') {\n      entry.atd = event.eventDateTime\n    }\n    // Use GTOT (gate-out) as departure indicator for depots/terminals\n    // This handles the first segment where container departs depot by truck\n    if (event.eventCode === 'GTOT' && event.eventClassifierCode === 'ACT' && !entry.atd) {\n      entry.atd = event.eventDateTime\n    }\n\n    // AIS port proximity events. Only ports survive into Route Details (waypoints +\n    // terminals are filtered out above), so these are the arrival/departure signals for\n    // AIS-tracked port calls \u2014 without them an AIS-only stop (e.g. a transshipment port\n    // not in the DCSA feed) has no ATA/ATD and its segment bars never turn green.\n    // Applied only when no carrier (DCSA) timestamp exists, so DCSA ATA/ATD always win.\n    // PARR = port arrival, PPRA = port proximity arrival, PPRD = port proximity departure.\n    if (\n      (event.eventCode === 'PARR' || event.eventCode === 'PPRA') &&\n      event.eventClassifierCode === 'ACT' &&\n      !entry.ata\n    ) {\n      entry.ata = event.eventDateTime\n    }\n    if (event.eventCode === 'PPRD' && event.eventClassifierCode === 'ACT' && !entry.atd) {\n      entry.atd = event.eventDateTime\n    }\n\n    // Track estimated/planned arrivals/departures (for delay calculation)\n    // Only store the first estimate (original plan) to compare against actual\n    if (event.eventCode === 'ARRI' && (event.eventClassifierCode === 'PLN' || event.eventClassifierCode === 'EST')) {\n      if (!entry.eta) entry.eta = event.eventDateTime\n    }\n    if (event.eventCode === 'DEPA' && (event.eventClassifierCode === 'PLN' || event.eventClassifierCode === 'EST')) {\n      if (!entry.etd) entry.etd = event.eventDateTime\n    }\n\n    // Mark transshipment if container was discharged and loaded\n    if (event.isTransshipmentMove || \n        (event.eventCode === 'DISC' || event.eventCode === 'LOAD')) {\n      entry.isTransshipment = true\n    }\n  }\n\n  // Convert to route stops\n  const stops: RouteStopEntry[] = []\n  const locations = Array.from(locationMap.entries())\n\n  for (let i = 0; i < locations.length; i++) {\n    const [key, data] = locations[i]\n    const isFirst = i === 0\n    const isLast = i === locations.length - 1\n\n    // Determine type based on position and context.\n    // An intermediate stop is a real 'transshipment' only when the cargo actually\n    // changed vessels here (isTransshipmentMove / DISC+LOAD); otherwise it's a plain\n    // 'port_call' \u2014 the same vessel calling en route (e.g. AIS port proximity events).\n    let type: 'origin' | 'transshipment' | 'port_call' | 'destination' =\n      data.isTransshipment ? 'transshipment' : 'port_call'\n\n    if (isFirst || key === context?.originUnlocode) {\n      type = 'origin'\n    } else if (isLast || key === context?.destinationUnlocode) {\n      type = 'destination'\n    }\n\n    // Get the last vessel entry (most recent vessel at this stop)\n    const vesselEntries = Array.from(data.vessels.entries())\n    const lastVessel = vesselEntries.length > 0 ? vesselEntries[vesselEntries.length - 1] : null\n    const vesselName = lastVessel ? lastVessel[0] : null\n    const vesselImo = lastVessel ? lastVessel[1] : null\n\n    stops.push({\n      location: data.name,\n      unlocode: data.unlocode,\n      type,\n      vesselName,\n      vesselImo,\n      ata: data.ata || null,\n      atd: data.atd || null,\n      eta: data.eta || null,\n      etd: data.etd || null,\n      // Facility details\n      countryCode: data.countryCode || null,\n      facilityCode: data.facilityCode || null,\n      facilityCodeListProvider: data.facilityCodeListProvider || null,\n      facilityTypeCode: data.facilityTypeCode || null,\n      facilityAddress: data.facilityAddress || null,\n      coords: data.coords || null,\n      operatorName: null, // Will be populated by BIC enrichment if needed\n    })\n  }\n\n  // Collapse consecutive stops at the same place into one port call. AIS port events for a\n  // single city can arrive under several POI codes (proximity vs actual arrival, different\n  // berths), which would otherwise render as duplicate rows (e.g. two \"Le Havre\") with split\n  // timestamps \u2014 breaking segment colors. Merge by location name, keeping the earliest\n  // arrival and latest departure so segment status is computed correctly.\n  const merged: RouteStopEntry[] = []\n  for (const stop of stops) {\n    const prev = merged[merged.length - 1]\n    if (prev && prev.location === stop.location) {\n      prev.ata = earliestIso(prev.ata, stop.ata)\n      prev.atd = latestIso(prev.atd, stop.atd)\n      prev.eta = earliestIso(prev.eta, stop.eta)\n      prev.etd = latestIso(prev.etd, stop.etd)\n      prev.vesselName = prev.vesselName ?? stop.vesselName\n      prev.vesselImo = prev.vesselImo ?? stop.vesselImo\n      // Prefer a real UN/LOCODE over a raw AIS POI grid code\n      if (prev.unlocode?.length !== 5 && stop.unlocode?.length === 5) prev.unlocode = stop.unlocode\n      prev.countryCode = prev.countryCode ?? stop.countryCode\n      prev.facilityCode = prev.facilityCode ?? stop.facilityCode\n      prev.facilityCodeListProvider = prev.facilityCodeListProvider ?? stop.facilityCodeListProvider\n      prev.facilityTypeCode = prev.facilityTypeCode ?? stop.facilityTypeCode\n      prev.facilityAddress = prev.facilityAddress ?? stop.facilityAddress\n      prev.coords = prev.coords ?? stop.coords\n      // Promote type if a merged member is an endpoint (origin/destination beats transshipment)\n      if (stop.type === 'origin') prev.type = 'origin'\n      else if (stop.type === 'destination' && prev.type !== 'origin') prev.type = 'destination'\n      else if (stop.type === 'transshipment' && prev.type === 'port_call') prev.type = 'transshipment'\n      continue\n    }\n    merged.push({ ...stop })\n  }\n\n  return merged\n}\n\n// \u2500\u2500\u2500 Event Mapping \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Maps a TrackingEvent entity to a CargoEventEntry for storage.\n * \n * @param event - The tracking event entity\n * @returns A simplified event entry suitable for JSONB storage\n */\nexport function mapTrackingEventToEntry(event: {\n  id: string\n  eventType: string\n  eventCode: string\n  eventClassifierCode?: string | null\n  eventDateTime: Date\n  description?: string | null\n  locationName?: string | null\n  locationUnlocode?: string | null\n  regionNamePl?: string | null\n  regionNameEn?: string | null\n  vesselName?: string | null\n  vesselImo?: string | null\n  voyageNumber?: string | null\n  isTransshipmentMove?: boolean | null\n  emptyIndicatorCode?: 'EMPTY' | 'LADEN' | null\n  // Facility fields\n  facilityCode?: string | null\n  facilityCodeListProvider?: 'BIC' | 'SMDG' | null\n  facilityTypeCode?: string | null\n  facilityAddress?: string | null\n  latitude?: number | null\n  longitude?: number | null\n  // Seal fields\n  seals?: SealInfo[] | null\n}): CargoEventEntry {\n  return {\n    id: event.id,\n    eventType: event.eventType,\n    eventCode: event.eventCode,\n    eventClassifierCode: event.eventClassifierCode as 'ACT' | 'PLN' | 'EST' | null,\n    eventDateTime: event.eventDateTime.toISOString(),\n    description: event.description || null,\n    locationName: event.locationName || null,\n    locationUnlocode: event.locationUnlocode || null,\n    regionNamePl: event.regionNamePl || null,\n    regionNameEn: event.regionNameEn || null,\n    vesselName: event.vesselName || null,\n    vesselImo: event.vesselImo || null,\n    voyageNumber: event.voyageNumber || null,\n    isTransshipmentMove: event.isTransshipmentMove ?? null,\n    emptyIndicatorCode: event.emptyIndicatorCode ?? null,\n    // Facility fields\n    facilityCode: event.facilityCode || null,\n    facilityCodeListProvider: event.facilityCodeListProvider || null,\n    facilityTypeCode: event.facilityTypeCode || null,\n    facilityAddress: event.facilityAddress || null,\n    latitude: event.latitude ?? null,\n    longitude: event.longitude ?? null,\n    // Seal fields\n    seals: event.seals ?? null,\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/route-inference.js

@@ -0,0 +1,106 @@
+function isPortOrTerminal(facilityTypeCode) {
+  if (!facilityTypeCode) return false;
+  return facilityTypeCode === "POTE" || facilityTypeCode === "INTE";
+}
+function isNonPortLocation(facilityTypeCode) {
+  if (!facilityTypeCode) return false;
+  return facilityTypeCode === "CLOC" || facilityTypeCode === "DEPO";
+}
+function inferRouteFromEvents(events) {
+  const result = {
+    originUnlocode: null,
+    destinationUnlocode: null,
+    confidence: {
+      origin: null,
+      destination: null
+    }
+  };
+  if (!events || events.length === 0) {
+    return result;
+  }
+  const sortedEvents = [...events].sort(
+    (a, b) => a.eventDateTime.getTime() - b.eventDateTime.getTime()
+  );
+  const plannedArriEvents = sortedEvents.filter(
+    (e) => e.eventType === "TRANSPORT" && e.eventCode === "ARRI" && (e.eventClassifierCode === "EST" || e.eventClassifierCode === "PLN") && e.locationUnlocode && !isNonPortLocation(e.facilityTypeCode)
+  );
+  if (plannedArriEvents.length > 0) {
+    const lastPlannedArri = plannedArriEvents[plannedArriEvents.length - 1];
+    result.destinationUnlocode = lastPlannedArri.locationUnlocode;
+    result.confidence.destination = "high";
+  }
+  if (!result.destinationUnlocode) {
+    const actArriEvents = sortedEvents.filter(
+      (e) => e.eventType === "TRANSPORT" && e.eventCode === "ARRI" && e.eventClassifierCode === "ACT" && e.modeOfTransport === "VESSEL" && e.locationUnlocode && !isNonPortLocation(e.facilityTypeCode)
+    );
+    if (actArriEvents.length > 0) {
+      const lastArri = actArriEvents[actArriEvents.length - 1];
+      result.destinationUnlocode = lastArri.locationUnlocode;
+      result.confidence.destination = "high";
+    }
+  }
+  if (!result.destinationUnlocode) {
+    const discEvents = sortedEvents.filter(
+      (e) => e.eventType === "EQUIPMENT" && e.eventCode === "DISC" && e.locationUnlocode && !isNonPortLocation(e.facilityTypeCode)
+    );
+    if (discEvents.length > 0) {
+      const lastDisc = discEvents[discEvents.length - 1];
+      result.destinationUnlocode = lastDisc.locationUnlocode;
+      result.confidence.destination = "medium";
+    }
+  }
+  const firstVesselDepa = sortedEvents.find(
+    (e) => e.eventType === "TRANSPORT" && e.eventCode === "DEPA" && e.eventClassifierCode === "ACT" && e.modeOfTransport === "VESSEL" && e.carrierExportVoyageNumber && e.locationUnlocode
+  );
+  if (firstVesselDepa?.locationUnlocode) {
+    result.originUnlocode = firstVesselDepa.locationUnlocode;
+    result.confidence.origin = "high";
+  }
+  if (!result.originUnlocode) {
+    const firstLoad = sortedEvents.find(
+      (e) => e.eventType === "EQUIPMENT" && e.eventCode === "LOAD" && e.eventClassifierCode === "ACT" && e.modeOfTransport === "VESSEL" && e.locationUnlocode
+    );
+    if (firstLoad?.locationUnlocode) {
+      result.originUnlocode = firstLoad.locationUnlocode;
+      result.confidence.origin = "high";
+    }
+  }
+  if (!result.originUnlocode) {
+    const firstGtinLaden = sortedEvents.find(
+      (e) => e.eventType === "EQUIPMENT" && e.eventCode === "GTIN" && e.emptyIndicatorCode === "LADEN" && e.eventClassifierCode === "ACT" && e.locationUnlocode && e.facilityTypeCode === "POTE"
+      // Port Terminal only
+    );
+    if (firstGtinLaden?.locationUnlocode) {
+      result.originUnlocode = firstGtinLaden.locationUnlocode;
+      result.confidence.origin = "medium";
+    }
+  }
+  if (!result.originUnlocode) {
+    const firstPlannedDepa = sortedEvents.find(
+      (e) => e.eventType === "TRANSPORT" && e.eventCode === "DEPA" && (e.eventClassifierCode === "EST" || e.eventClassifierCode === "PLN") && e.modeOfTransport === "VESSEL" && e.locationUnlocode
+    );
+    if (firstPlannedDepa?.locationUnlocode) {
+      result.originUnlocode = firstPlannedDepa.locationUnlocode;
+      result.confidence.origin = "medium";
+    }
+  }
+  if (!result.originUnlocode) {
+    const firstPlannedLoad = sortedEvents.find(
+      (e) => e.eventType === "EQUIPMENT" && e.eventCode === "LOAD" && (e.eventClassifierCode === "EST" || e.eventClassifierCode === "PLN") && e.modeOfTransport === "VESSEL" && e.locationUnlocode
+    );
+    if (firstPlannedLoad?.locationUnlocode) {
+      result.originUnlocode = firstPlannedLoad.locationUnlocode;
+      result.confidence.origin = "medium";
+    }
+  }
+  return result;
+}
+function isValidUnlocode(code) {
+  if (!code) return false;
+  return /^[A-Z]{2}[A-Z0-9]{3}$/.test(code.toUpperCase());
+}
+export {
+  inferRouteFromEvents,
+  isValidUnlocode
+};
+//# sourceMappingURL=route-inference.js.map

package/dist/modules/shipment_tracking/lib/route-inference.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/route-inference.ts"],
+  "sourcesContent": ["import type { CarrierFetchedEvent } from './carrier-adapter'\n\nexport interface InferredRoute {\n  originUnlocode: string | null\n  destinationUnlocode: string | null\n  confidence: {\n    origin: 'high' | 'medium' | 'low' | null\n    destination: 'high' | 'medium' | 'low' | null\n  }\n}\n\n/**\n * Checks if the facility type represents a port or intermodal terminal.\n * Used to filter out client locations (CLOC) and depots (DEPO) when inferring ports.\n *\n * Valid facility types for port inference:\n * - POTE: Port Terminal\n * - INTE: Intermodal Terminal (rail/truck interchange)\n */\nfunction isPortOrTerminal(facilityTypeCode: string | null | undefined): boolean {\n  if (!facilityTypeCode) return false\n  return facilityTypeCode === 'POTE' || facilityTypeCode === 'INTE'\n}\n\n/**\n * Checks if the facility type is a known non-port location (client site or depot).\n * Used to filter out these locations when inferring destination ports.\n */\nfunction isNonPortLocation(facilityTypeCode: string | null | undefined): boolean {\n  if (!facilityTypeCode) return false\n  // CLOC = Client Location, DEPO = Depot - these are inland delivery points\n  return facilityTypeCode === 'CLOC' || facilityTypeCode === 'DEPO'\n}\n\n/**\n * Infers origin and destination ports from DCSA tracking events.\n *\n * Strategy for DESTINATION:\n * 1. Last EST/PLN ARRI event at a port terminal (POTE/INTE) \u2192 high confidence\n * 2. Last ACT ARRI on VESSEL at a port terminal \u2192 high confidence\n * 3. Last DISC event at a port terminal \u2192 medium confidence\n * 4. Fallback: Last ARRI/DISC at any location (when no port data available)\n *\n * IMPORTANT: We filter by facilityTypeCode to exclude client locations (CLOC)\n * and depots (DEPO) which are inland delivery points, not ports.\n *\n * Strategy for ORIGIN:\n * 1. First ACT DEPA on VESSEL with exportVoyageNumber \u2192 high confidence (departure from load port)\n * 2. First LOAD event on VESSEL \u2192 high confidence (where cargo was first loaded)\n * 3. First GTIN (LADEN) event \u2192 medium confidence (gate-in at origin)\n *\n * Key insight:\n * - exportVoyageNumber indicates outbound leg (origin side)\n * - importVoyageNumber indicates inbound leg (destination side)\n */\nexport function inferRouteFromEvents(events: CarrierFetchedEvent[]): InferredRoute {\n  const result: InferredRoute = {\n    originUnlocode: null,\n    destinationUnlocode: null,\n    confidence: {\n      origin: null,\n      destination: null,\n    },\n  }\n\n  if (!events || events.length === 0) {\n    return result\n  }\n\n  // Sort events by datetime for chronological processing\n  const sortedEvents = [...events].sort(\n    (a, b) => a.eventDateTime.getTime() - b.eventDateTime.getTime()\n  )\n\n  // \u2500\u2500\u2500 DESTINATION INFERENCE \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  // For transshipment voyages, there are multiple ARRI events (one per port).\n  // The LAST arrival event at a PORT TERMINAL is the final destination.\n  // We explicitly filter out client locations (CLOC) and depots (DEPO).\n\n  // Strategy 1: Look for LAST ARRI event (EST or PLN), excluding known non-port locations\n  // PLN (planned) and EST (estimated) both indicate scheduled arrivals.\n  // We take the LAST one as the final destination, filtering out client locations/depots.\n  // Note: We use \"exclude non-port\" rather than \"include only port\" to handle cases\n  // where facilityTypeCode is not provided (common in many carriers' responses).\n  const plannedArriEvents = sortedEvents.filter(\n    (e) =>\n      e.eventType === 'TRANSPORT' &&\n      e.eventCode === 'ARRI' &&\n      (e.eventClassifierCode === 'EST' || e.eventClassifierCode === 'PLN') &&\n      e.locationUnlocode &&\n      !isNonPortLocation(e.facilityTypeCode)\n  )\n\n  if (plannedArriEvents.length > 0) {\n    // Take the last planned arrival - this is the final port destination\n    const lastPlannedArri = plannedArriEvents[plannedArriEvents.length - 1]\n    result.destinationUnlocode = lastPlannedArri.locationUnlocode!\n    // High confidence if we have facility type info confirming it's a port, otherwise still high for PLN/EST\n    result.confidence.destination = 'high'\n  }\n\n  // Strategy 2: Look for last ACT ARRI on VESSEL, excluding known non-port locations\n  if (!result.destinationUnlocode) {\n    const actArriEvents = sortedEvents.filter(\n      (e) =>\n        e.eventType === 'TRANSPORT' &&\n        e.eventCode === 'ARRI' &&\n        e.eventClassifierCode === 'ACT' &&\n        e.modeOfTransport === 'VESSEL' &&\n        e.locationUnlocode &&\n        !isNonPortLocation(e.facilityTypeCode)\n    )\n\n    if (actArriEvents.length > 0) {\n      const lastArri = actArriEvents[actArriEvents.length - 1]\n      result.destinationUnlocode = lastArri.locationUnlocode!\n      result.confidence.destination = 'high'\n    }\n  }\n\n  // Strategy 3: Look for last DISC event, excluding known non-port locations\n  if (!result.destinationUnlocode) {\n    const discEvents = sortedEvents.filter(\n      (e) =>\n        e.eventType === 'EQUIPMENT' &&\n        e.eventCode === 'DISC' &&\n        e.locationUnlocode &&\n        !isNonPortLocation(e.facilityTypeCode)\n    )\n\n    if (discEvents.length > 0) {\n      const lastDisc = discEvents[discEvents.length - 1]\n      result.destinationUnlocode = lastDisc.locationUnlocode!\n      result.confidence.destination = 'medium'\n    }\n  }\n\n  // \u2500\u2500\u2500 ORIGIN INFERENCE \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n  // Strategy 1: First ACT DEPA on VESSEL with exportVoyageNumber\n  const firstVesselDepa = sortedEvents.find(\n    (e) =>\n      e.eventType === 'TRANSPORT' &&\n      e.eventCode === 'DEPA' &&\n      e.eventClassifierCode === 'ACT' &&\n      e.modeOfTransport === 'VESSEL' &&\n      e.carrierExportVoyageNumber &&\n      e.locationUnlocode\n  )\n\n  if (firstVesselDepa?.locationUnlocode) {\n    result.originUnlocode = firstVesselDepa.locationUnlocode\n    result.confidence.origin = 'high'\n  }\n\n  // Strategy 2: First LOAD event on VESSEL\n  if (!result.originUnlocode) {\n    const firstLoad = sortedEvents.find(\n      (e) =>\n        e.eventType === 'EQUIPMENT' &&\n        e.eventCode === 'LOAD' &&\n        e.eventClassifierCode === 'ACT' &&\n        e.modeOfTransport === 'VESSEL' &&\n        e.locationUnlocode\n    )\n\n    if (firstLoad?.locationUnlocode) {\n      result.originUnlocode = firstLoad.locationUnlocode\n      result.confidence.origin = 'high'\n    }\n  }\n\n  // Strategy 3: First GTIN (LADEN) event at a port terminal (fallback)\n  // Only consider events at port terminals (POTE), not inland depots (DEPO)\n  if (!result.originUnlocode) {\n    const firstGtinLaden = sortedEvents.find(\n      (e) =>\n        e.eventType === 'EQUIPMENT' &&\n        e.eventCode === 'GTIN' &&\n        e.emptyIndicatorCode === 'LADEN' &&\n        e.eventClassifierCode === 'ACT' &&\n        e.locationUnlocode &&\n        e.facilityTypeCode === 'POTE' // Port Terminal only\n    )\n\n    if (firstGtinLaden?.locationUnlocode) {\n      result.originUnlocode = firstGtinLaden.locationUnlocode\n      result.confidence.origin = 'medium'\n    }\n  }\n\n  // Strategy 4: First EST/PLN DEPA on VESSEL (for pre-departure tracking)\n  // When no actual events exist yet, use planned departure to infer origin\n  if (!result.originUnlocode) {\n    const firstPlannedDepa = sortedEvents.find(\n      (e) =>\n        e.eventType === 'TRANSPORT' &&\n        e.eventCode === 'DEPA' &&\n        (e.eventClassifierCode === 'EST' || e.eventClassifierCode === 'PLN') &&\n        e.modeOfTransport === 'VESSEL' &&\n        e.locationUnlocode\n    )\n\n    if (firstPlannedDepa?.locationUnlocode) {\n      result.originUnlocode = firstPlannedDepa.locationUnlocode\n      result.confidence.origin = 'medium' // Lower confidence for planned events\n    }\n  }\n\n  // Strategy 5: First PLN LOAD event on VESSEL (for pre-departure tracking)\n  if (!result.originUnlocode) {\n    const firstPlannedLoad = sortedEvents.find(\n      (e) =>\n        e.eventType === 'EQUIPMENT' &&\n        e.eventCode === 'LOAD' &&\n        (e.eventClassifierCode === 'EST' || e.eventClassifierCode === 'PLN') &&\n        e.modeOfTransport === 'VESSEL' &&\n        e.locationUnlocode\n    )\n\n    if (firstPlannedLoad?.locationUnlocode) {\n      result.originUnlocode = firstPlannedLoad.locationUnlocode\n      result.confidence.origin = 'medium'\n    }\n  }\n\n  return result\n}\n\n/**\n * Validates a UN/LOCODE format.\n * Format: 2 letters (country) + 3 alphanumeric (location)\n * Example: CNYTN (China, Yantian), PLGDN (Poland, Gdansk)\n */\nexport function isValidUnlocode(code: string | null | undefined): boolean {\n  if (!code) return false\n  return /^[A-Z]{2}[A-Z0-9]{3}$/.test(code.toUpperCase())\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/schedule-generator.js

@@ -0,0 +1,63 @@
+const DEFAULT_WINDOW_DAYS = 120;
+const JITTER_RANGE_HOURS = 4;
+function addDays(date, days) {
+  const result = new Date(date);
+  result.setDate(result.getDate() + days);
+  return result;
+}
+function addHours(date, hours) {
+  const result = new Date(date);
+  result.setTime(result.getTime() + hours * 60 * 60 * 1e3);
+  return result;
+}
+function randomJitter() {
+  return Math.random() * JITTER_RANGE_HOURS - JITTER_RANGE_HOURS / 2;
+}
+function generatePollSchedule(input) {
+  const now = /* @__PURE__ */ new Date();
+  if (input?.ata) {
+    return [];
+  }
+  let startDate;
+  let endDate;
+  if (input?.etd) {
+    startDate = addDays(input.etd, -7);
+  } else if (input?.atd) {
+    startDate = input.atd;
+  } else {
+    startDate = now;
+  }
+  if (input?.eta) {
+    endDate = addDays(input.eta, 14);
+  } else {
+    endDate = addDays(startDate, DEFAULT_WINDOW_DAYS);
+  }
+  if (startDate < now) {
+    startDate = now;
+  }
+  const dates = [];
+  let current = new Date(startDate);
+  while (current <= endDate) {
+    const withJitter = addHours(current, randomJitter());
+    if (withJitter > now) {
+      dates.push(withJitter.toISOString());
+    }
+    current = addDays(current, 1);
+  }
+  return dates;
+}
+function getNextPollDate(schedule) {
+  const now = Date.now();
+  for (const dateStr of schedule) {
+    const date = new Date(dateStr);
+    if (date.getTime() > now) {
+      return date;
+    }
+  }
+  return null;
+}
+export {
+  generatePollSchedule,
+  getNextPollDate
+};
+//# sourceMappingURL=schedule-generator.js.map

package/dist/modules/shipment_tracking/lib/schedule-generator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/schedule-generator.ts"],
+  "sourcesContent": ["const DEFAULT_WINDOW_DAYS = 120 // 4 months\nconst JITTER_RANGE_HOURS = 4\n\nfunction addDays(date: Date, days: number): Date {\n  const result = new Date(date)\n  result.setDate(result.getDate() + days)\n  return result\n}\n\nfunction addHours(date: Date, hours: number): Date {\n  const result = new Date(date)\n  result.setTime(result.getTime() + hours * 60 * 60 * 1000)\n  return result\n}\n\nfunction randomJitter(): number {\n  return Math.random() * JITTER_RANGE_HOURS - JITTER_RANGE_HOURS / 2\n}\n\n/**\n * Generates a list of daily poll dates with random time jitter.\n *\n * - If ETD and ETA are provided, generates dates from ETD - 7 days to ETA + 14 days.\n * - If only ETD is provided, generates from ETD - 7 days for the default window.\n * - If nothing is provided, starts from now for the default window.\n * - Jitter is +/- 2 hours to spread API load.\n */\nexport function generatePollSchedule(input?: {\n  etd?: Date | null\n  eta?: Date | null\n  atd?: Date | null\n  ata?: Date | null\n}): string[] {\n  const now = new Date()\n\n  // If already delivered (ATA present), no more polling needed\n  if (input?.ata) {\n    return []\n  }\n\n  let startDate: Date\n  let endDate: Date\n\n  if (input?.etd) {\n    startDate = addDays(input.etd, -7)\n  } else if (input?.atd) {\n    startDate = input.atd\n  } else {\n    startDate = now\n  }\n\n  if (input?.eta) {\n    endDate = addDays(input.eta, 14)\n  } else {\n    endDate = addDays(startDate, DEFAULT_WINDOW_DAYS)\n  }\n\n  // Ensure start is not in the past\n  if (startDate < now) {\n    startDate = now\n  }\n\n  const dates: string[] = []\n  let current = new Date(startDate)\n\n  while (current <= endDate) {\n    const withJitter = addHours(current, randomJitter())\n    // Only include future dates\n    if (withJitter > now) {\n      dates.push(withJitter.toISOString())\n    }\n    current = addDays(current, 1)\n  }\n\n  return dates\n}\n\n/**\n * Given a schedule (array of ISO date strings), returns the next poll date after now.\n */\nexport function getNextPollDate(schedule: string[]): Date | null {\n  const now = Date.now()\n\n  for (const dateStr of schedule) {\n    const date = new Date(dateStr)\n    if (date.getTime() > now) {\n      return date\n    }\n  }\n\n  return null\n}\n"],
+  "mappings": "AAAA,MAAM,sBAAsB;AAC5B,MAAM,qBAAqB;AAE3B,SAAS,QAAQ,MAAY,MAAoB;AAC/C,QAAM,SAAS,IAAI,KAAK,IAAI;AAC5B,SAAO,QAAQ,OAAO,QAAQ,IAAI,IAAI;AACtC,SAAO;AACT;AAEA,SAAS,SAAS,MAAY,OAAqB;AACjD,QAAM,SAAS,IAAI,KAAK,IAAI;AAC5B,SAAO,QAAQ,OAAO,QAAQ,IAAI,QAAQ,KAAK,KAAK,GAAI;AACxD,SAAO;AACT;AAEA,SAAS,eAAuB;AAC9B,SAAO,KAAK,OAAO,IAAI,qBAAqB,qBAAqB;AACnE;AAUO,SAAS,qBAAqB,OAKxB;AACX,QAAM,MAAM,oBAAI,KAAK;AAGrB,MAAI,OAAO,KAAK;AACd,WAAO,CAAC;AAAA,EACV;AAEA,MAAI;AACJ,MAAI;AAEJ,MAAI,OAAO,KAAK;AACd,gBAAY,QAAQ,MAAM,KAAK,EAAE;AAAA,EACnC,WAAW,OAAO,KAAK;AACrB,gBAAY,MAAM;AAAA,EACpB,OAAO;AACL,gBAAY;AAAA,EACd;AAEA,MAAI,OAAO,KAAK;AACd,cAAU,QAAQ,MAAM,KAAK,EAAE;AAAA,EACjC,OAAO;AACL,cAAU,QAAQ,WAAW,mBAAmB;AAAA,EAClD;AAGA,MAAI,YAAY,KAAK;AACnB,gBAAY;AAAA,EACd;AAEA,QAAM,QAAkB,CAAC;AACzB,MAAI,UAAU,IAAI,KAAK,SAAS;AAEhC,SAAO,WAAW,SAAS;AACzB,UAAM,aAAa,SAAS,SAAS,aAAa,CAAC;AAEnD,QAAI,aAAa,KAAK;AACpB,YAAM,KAAK,WAAW,YAAY,CAAC;AAAA,IACrC;AACA,cAAU,QAAQ,SAAS,CAAC;AAAA,EAC9B;AAEA,SAAO;AACT;AAKO,SAAS,gBAAgB,UAAiC;AAC/D,QAAM,MAAM,KAAK,IAAI;AAErB,aAAW,WAAW,UAAU;AAC9B,UAAM,OAAO,IAAI,KAAK,OAAO;AAC7B,QAAI,KAAK,QAAQ,IAAI,KAAK;AACxB,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;",
+  "names": []
+}