@freighttech/shipment-tracking 0.6.0

package/dist/modules/shipment_tracking/lib/current-vessel.js

@@ -0,0 +1,149 @@
+function getSevenDaysAgo() {
+  const date = /* @__PURE__ */ new Date();
+  date.setDate(date.getDate() - 7);
+  return date.toISOString();
+}
+function findLastVesselFromStops(routeStops, cargoEvents) {
+  for (let i = routeStops.length - 1; i >= 0; i--) {
+    const stop = routeStops[i];
+    if (stop.vesselName) {
+      const vesselImo = stop.vesselImo || findVesselImoFromEvents(stop.vesselName, cargoEvents);
+      return { vesselName: stop.vesselName, vesselImo };
+    }
+  }
+  return { vesselName: null, vesselImo: null };
+}
+function getCurrentVessel(routeStops, cargoEvents, fallbackVessel) {
+  const defaultResult = {
+    vesselName: fallbackVessel?.vesselName ?? null,
+    vesselImo: fallbackVessel?.vesselImo ?? null,
+    status: "not_departed",
+    isPlannedVessel: true,
+    traceFrom: getSevenDaysAgo()
+  };
+  if (!routeStops || routeStops.length === 0) {
+    return defaultResult;
+  }
+  const destination = routeStops.find((s) => s.type === "destination");
+  if (destination?.ata) {
+    const lastVesselInfo = findLastVesselFromStops(routeStops, cargoEvents);
+    return {
+      vesselName: lastVesselInfo.vesselName,
+      vesselImo: lastVesselInfo.vesselImo,
+      status: "delivered",
+      currentPort: destination.location,
+      isPlannedVessel: false
+      // No traceFrom needed for delivered containers (map not shown)
+    };
+  }
+  for (let i = routeStops.length - 1; i >= 0; i--) {
+    const stop = routeStops[i];
+    const nextStop = routeStops[i + 1];
+    if (stop.atd && nextStop && !nextStop.ata) {
+      const vesselImo2 = stop.vesselImo || findVesselImoFromEvents(stop.vesselName, cargoEvents) || fallbackVessel?.vesselImo || null;
+      return {
+        vesselName: stop.vesselName ?? null,
+        vesselImo: vesselImo2,
+        status: "in_transit",
+        currentLeg: {
+          fromPort: stop.location,
+          toPort: nextStop.location
+        },
+        isPlannedVessel: false,
+        traceFrom: stop.atd
+        // Use ATD from departure port
+      };
+    }
+    if (stop.ata && !stop.atd) {
+      if (nextStop) {
+        const vesselImo2 = nextStop.vesselImo || findVesselImoFromEvents(nextStop.vesselName, cargoEvents) || fallbackVessel?.vesselImo || null;
+        return {
+          vesselName: nextStop.vesselName ?? null,
+          vesselImo: vesselImo2,
+          status: "at_port",
+          currentPort: stop.location,
+          isPlannedVessel: true,
+          traceFrom: getSevenDaysAgo()
+          // Last 7 days for planned vessel
+        };
+      }
+      return {
+        vesselName: null,
+        vesselImo: null,
+        status: "at_port",
+        currentPort: stop.location,
+        isPlannedVessel: false,
+        traceFrom: getSevenDaysAgo()
+      };
+    }
+  }
+  const origin = routeStops[0];
+  const vesselImo = origin?.vesselImo || findVesselImoFromEvents(origin?.vesselName, cargoEvents);
+  return {
+    vesselName: origin?.vesselName ?? fallbackVessel?.vesselName ?? null,
+    vesselImo: vesselImo ?? fallbackVessel?.vesselImo ?? null,
+    status: "not_departed",
+    currentPort: origin?.location,
+    isPlannedVessel: true,
+    traceFrom: getSevenDaysAgo()
+    // Last 7 days for planned vessel
+  };
+}
+function findVesselImoFromEvents(vesselName, events) {
+  if (!vesselName || !events || events.length === 0) {
+    return null;
+  }
+  const eventWithImo = events.find(
+    (e) => e.vesselName === vesselName && e.vesselImo
+  );
+  return eventWithImo?.vesselImo ?? null;
+}
+function getVesselStatusDescription(info) {
+  switch (info.status) {
+    case "in_transit":
+      return {
+        key: "shipment_tracking.map.inTransit",
+        params: {
+          destination: info.currentLeg?.toPort ?? ""
+        }
+      };
+    case "at_port":
+      if (info.vesselName) {
+        return {
+          key: "shipment_tracking.map.atPortAwaitingVessel",
+          params: {
+            port: info.currentPort ?? "",
+            vessel: info.vesselName
+          }
+        };
+      }
+      return {
+        key: "shipment_tracking.map.atPort",
+        params: {
+          port: info.currentPort ?? ""
+        }
+      };
+    case "not_departed":
+      if (info.vesselName) {
+        return {
+          key: "shipment_tracking.map.awaitingDeparture",
+          params: {
+            vessel: info.vesselName
+          }
+        };
+      }
+      return {
+        key: "shipment_tracking.map.notDeparted"
+      };
+    case "delivered":
+      return {
+        key: "shipment_tracking.map.delivered"
+      };
+  }
+}
+export {
+  findVesselImoFromEvents,
+  getCurrentVessel,
+  getVesselStatusDescription
+};
+//# sourceMappingURL=current-vessel.js.map

package/dist/modules/shipment_tracking/lib/current-vessel.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/current-vessel.ts"],
+  "sourcesContent": ["/**\n * Current vessel derivation utilities for shipment tracking.\n *\n * Determines which vessel the container is currently on (or waiting for)\n * based on shipment progress through route stops.\n */\n\nimport type { RouteStopEntry, CargoEventEntry } from './route-extraction'\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 * Container's current tracking status.\n */\nexport type VesselTrackingStatus =\n  | 'in_transit'    // Container is on a vessel moving between ports\n  | 'at_port'       // Container is at a port (waiting for next vessel or just arrived)\n  | 'not_departed'  // Container hasn't started journey yet (at origin)\n  | 'delivered'     // Container has arrived at final destination\n\n/**\n * Information about the current or planned vessel for tracking.\n */\nexport interface CurrentVesselInfo {\n  /** Current or planned vessel name */\n  vesselName: string | null\n  /** Current or planned vessel IMO for tracking */\n  vesselImo: string | null\n  /** Container's current status */\n  status: VesselTrackingStatus\n  /** Current leg info (if in transit) */\n  currentLeg?: {\n    fromPort: string\n    toPort: string\n  }\n  /** Port name where container currently is (if at_port or not_departed) */\n  currentPort?: string\n  /** Whether the vessel shown is planned (not yet departed) vs currently carrying container */\n  isPlannedVessel: boolean\n  /** Start date for trace - ATD from departure port (in_transit) or 7 days ago (planned) */\n  traceFrom?: string\n}\n\n// \u2500\u2500\u2500 Helper Functions \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 * Returns ISO 8601 date string for 7 days ago.\n * Used as default trace start time for planned vessels.\n */\nfunction getSevenDaysAgo(): string {\n  const date = new Date()\n  date.setDate(date.getDate() - 7)\n  return date.toISOString()\n}\n\n// \u2500\u2500\u2500 Helper Functions \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 * Finds the last vessel that carried the container by searching route stops backwards.\n * Used for delivered shipments to show which vessel completed the journey.\n */\nfunction findLastVesselFromStops(\n  routeStops: RouteStopEntry[],\n  cargoEvents: CargoEventEntry[] | null | undefined\n): { vesselName: string | null; vesselImo: string | null } {\n  // Work backwards from the last stop to find a stop with vessel info\n  for (let i = routeStops.length - 1; i >= 0; i--) {\n    const stop = routeStops[i]\n    if (stop.vesselName) {\n      const vesselImo = stop.vesselImo || findVesselImoFromEvents(stop.vesselName, cargoEvents)\n      return { vesselName: stop.vesselName, vesselImo }\n    }\n  }\n  return { vesselName: null, vesselImo: null }\n}\n\n// \u2500\u2500\u2500 Main Function \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 * Determines the current vessel based on shipment progress through route stops.\n *\n * Algorithm:\n * 1. If final destination has ATA \u2192 Container delivered, no vessel to track\n * 2. Find the latest stop with ATD where next stop doesn't have ATA\n *    \u2192 Container is in transit on this leg's vessel\n * 3. Find stop with ATA but no ATD (container at port waiting)\n *    \u2192 Return next leg's planned vessel if available\n * 4. No stops have ATD \u2192 Container not departed yet\n *    \u2192 Return first leg's planned vessel\n *\n * @param routeStops - Array of route stops from shipment\n * @param cargoEvents - Array of cargo events (used to find vessel IMO if not in stops)\n * @param fallbackVessel - Fallback vessel info from shipment entity\n * @returns CurrentVesselInfo with vessel details and status\n */\nexport function getCurrentVessel(\n  routeStops: RouteStopEntry[] | null | undefined,\n  cargoEvents: CargoEventEntry[] | null | undefined,\n  fallbackVessel?: { vesselName?: string | null; vesselImo?: string | null }\n): CurrentVesselInfo {\n  // Default result when no data available\n  const defaultResult: CurrentVesselInfo = {\n    vesselName: fallbackVessel?.vesselName ?? null,\n    vesselImo: fallbackVessel?.vesselImo ?? null,\n    status: 'not_departed',\n    isPlannedVessel: true,\n    traceFrom: getSevenDaysAgo(),\n  }\n\n  if (!routeStops || routeStops.length === 0) {\n    return defaultResult\n  }\n\n  // Check if container is delivered (final destination has ATA)\n  const destination = routeStops.find((s) => s.type === 'destination')\n  if (destination?.ata) {\n    // Find the last vessel that carried the container (for display purposes)\n    // Work backwards from destination to find a stop with vessel info\n    const lastVesselInfo = findLastVesselFromStops(routeStops, cargoEvents)\n    return {\n      vesselName: lastVesselInfo.vesselName,\n      vesselImo: lastVesselInfo.vesselImo,\n      status: 'delivered',\n      currentPort: destination.location,\n      isPlannedVessel: false,\n      // No traceFrom needed for delivered containers (map not shown)\n    }\n  }\n\n  // Find where the container currently is\n  // Look for the latest stop with ATD where the next stop doesn't have ATA yet\n  for (let i = routeStops.length - 1; i >= 0; i--) {\n    const stop = routeStops[i]\n    const nextStop = routeStops[i + 1]\n\n    // Case 1: Stop has ATD and next stop exists but doesn't have ATA\n    // \u2192 Container is in transit between these stops\n    if (stop.atd && nextStop && !nextStop.ata) {\n      const vesselImo = stop.vesselImo || findVesselImoFromEvents(stop.vesselName, cargoEvents) || fallbackVessel?.vesselImo || null\n      return {\n        vesselName: stop.vesselName ?? null,\n        vesselImo,\n        status: 'in_transit',\n        currentLeg: {\n          fromPort: stop.location,\n          toPort: nextStop.location,\n        },\n        isPlannedVessel: false,\n        traceFrom: stop.atd,  // Use ATD from departure port\n      }\n    }\n\n    // Case 2: Stop has ATA but no ATD (container is at this port)\n    // \u2192 Return the next leg's vessel as planned vessel\n    if (stop.ata && !stop.atd) {\n      // Look for next stop's vessel\n      if (nextStop) {\n        const vesselImo =\n          nextStop.vesselImo || findVesselImoFromEvents(nextStop.vesselName, cargoEvents) || fallbackVessel?.vesselImo || null\n        return {\n          vesselName: nextStop.vesselName ?? null,\n          vesselImo,\n          status: 'at_port',\n          currentPort: stop.location,\n          isPlannedVessel: true,\n          traceFrom: getSevenDaysAgo(),  // Last 7 days for planned vessel\n        }\n      }\n      // At final stop but no ATA on destination (shouldn't happen normally)\n      return {\n        vesselName: null,\n        vesselImo: null,\n        status: 'at_port',\n        currentPort: stop.location,\n        isPlannedVessel: false,\n        traceFrom: getSevenDaysAgo(),\n      }\n    }\n  }\n\n  // Case 3: No stops have ATD \u2192 Container hasn't departed yet\n  // Return first leg's vessel as planned\n  const origin = routeStops[0]\n  const vesselImo = origin?.vesselImo || findVesselImoFromEvents(origin?.vesselName, cargoEvents)\n\n  return {\n    vesselName: origin?.vesselName ?? fallbackVessel?.vesselName ?? null,\n    vesselImo: vesselImo ?? fallbackVessel?.vesselImo ?? null,\n    status: 'not_departed',\n    currentPort: origin?.location,\n    isPlannedVessel: true,\n    traceFrom: getSevenDaysAgo(),  // Last 7 days for planned vessel\n  }\n}\n\n// \u2500\u2500\u2500 More Helper Functions \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 * Find vessel IMO from cargo events by vessel name.\n * Used when RouteStopEntry only has vesselName but needs IMO.\n *\n * @param vesselName - Vessel name to search for\n * @param events - Array of cargo events\n * @returns Vessel IMO if found, null otherwise\n */\nexport function findVesselImoFromEvents(\n  vesselName: string | null | undefined,\n  events: CargoEventEntry[] | null | undefined\n): string | null {\n  if (!vesselName || !events || events.length === 0) {\n    return null\n  }\n\n  // Find any event with matching vessel name that has an IMO\n  const eventWithImo = events.find(\n    (e) => e.vesselName === vesselName && e.vesselImo\n  )\n\n  return eventWithImo?.vesselImo ?? null\n}\n\n/**\n * Get a human-readable description of the current vessel status.\n * Useful for UI display.\n *\n * @param info - Current vessel info\n * @returns Status description object with keys for i18n\n */\nexport function getVesselStatusDescription(info: CurrentVesselInfo): {\n  key: string\n  params?: Record<string, string>\n} {\n  switch (info.status) {\n    case 'in_transit':\n      return {\n        key: 'shipment_tracking.map.inTransit',\n        params: {\n          destination: info.currentLeg?.toPort ?? '',\n        },\n      }\n    case 'at_port':\n      if (info.vesselName) {\n        return {\n          key: 'shipment_tracking.map.atPortAwaitingVessel',\n          params: {\n            port: info.currentPort ?? '',\n            vessel: info.vesselName,\n          },\n        }\n      }\n      return {\n        key: 'shipment_tracking.map.atPort',\n        params: {\n          port: info.currentPort ?? '',\n        },\n      }\n    case 'not_departed':\n      if (info.vesselName) {\n        return {\n          key: 'shipment_tracking.map.awaitingDeparture',\n          params: {\n            vessel: info.vesselName,\n          },\n        }\n      }\n      return {\n        key: 'shipment_tracking.map.notDeparted',\n      }\n    case 'delivered':\n      return {\n        key: 'shipment_tracking.map.delivered',\n      }\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["vesselImo"]
+}

package/dist/modules/shipment_tracking/lib/dcsa-event-mapping.js

@@ -0,0 +1,124 @@
+function mapDcsaEventToWebhookType(input) {
+  const { eventType, eventCode, eventClassifierCode } = input;
+  const code = eventCode.toUpperCase();
+  const isActual = eventClassifierCode === "ACT";
+  const isEstimatedOrPlanned = eventClassifierCode === "EST" || eventClassifierCode === "PLN";
+  if (eventType === "TRANSPORT") {
+    switch (code) {
+      case "DEPA":
+        if (isActual) return "shipment_tracking.transport.departed";
+        if (isEstimatedOrPlanned) return "shipment_tracking.transport.etd_updated";
+        return "shipment_tracking.transport.etd_updated";
+      // Default to ETD update
+      case "ARRI":
+        if (isActual) return "shipment_tracking.transport.arrived";
+        if (isEstimatedOrPlanned) return "shipment_tracking.transport.eta_updated";
+        return "shipment_tracking.transport.eta_updated";
+      // Default to ETA update
+      case "OMIT":
+        return "shipment_tracking.transport.omitted";
+    }
+  }
+  if (eventType === "EQUIPMENT") {
+    switch (code) {
+      // Loading/Discharge
+      case "LOAD":
+        return "shipment_tracking.equipment.loaded";
+      case "DISC":
+        return "shipment_tracking.equipment.discharged";
+      // Gate movements
+      case "GTIN":
+        return "shipment_tracking.equipment.gate_in";
+      case "GTOT":
+        return "shipment_tracking.equipment.gate_out";
+      // Availability
+      case "AVPU":
+        return "shipment_tracking.equipment.available_pickup";
+      case "AVDO":
+        return "shipment_tracking.equipment.gate_in";
+      // Customs
+      case "CUSR":
+        return "shipment_tracking.equipment.customs_released";
+      case "CUSS":
+      // Customs selected for scan
+      case "CUSI":
+        return "shipment_tracking.equipment.inspected";
+      // Inspection
+      case "INSP":
+        return "shipment_tracking.equipment.inspected";
+      // Delivery
+      case "DLVR":
+        if (isActual) return "shipment_tracking.shipment.delivered";
+        break;
+      // Pick-up/Drop-off (physical movement)
+      case "PICK":
+        return "shipment_tracking.equipment.gate_out";
+      case "DROP":
+        return "shipment_tracking.equipment.gate_in";
+      // Stuffing/Stripping
+      case "STUF":
+      // Stuffed (cargo loaded into container)
+      case "STRP":
+        break;
+      // Sealing
+      case "RSEA":
+      // Resealed
+      case "RMVD":
+        break;
+      // Transshipment crossing
+      case "CROS":
+        return "shipment_tracking.equipment.discharged";
+    }
+  }
+  if (eventType === "SHIPMENT") {
+    switch (code) {
+      case "CONF":
+      // Confirmed
+      case "BOOK":
+        return "shipment_tracking.shipment.booked";
+    }
+  }
+  return "shipment_tracking.tracking_event.created";
+}
+function isSignificantMilestone(input) {
+  const webhookType = mapDcsaEventToWebhookType(input);
+  return webhookType !== "shipment_tracking.tracking_event.created";
+}
+const DCSA_EQUIPMENT_EVENT_CODES = {
+  LOAD: "Loaded onto transport",
+  DISC: "Discharged from transport",
+  GTIN: "Gated in (entered facility)",
+  GTOT: "Gated out (terminal)",
+  STUF: "Stuffed (cargo loaded into container)",
+  STRP: "Stripped (cargo removed from container)",
+  PICK: "Pick-up by consignee/trucker",
+  DROP: "Drop-off at facility",
+  INSP: "Inspected",
+  RSEA: "Resealed",
+  RMVD: "Seal removed",
+  AVPU: "Available for pick-up",
+  AVDO: "Available for drop-off",
+  CUSS: "Customs selected for scan",
+  CUSI: "Customs selected for inspection",
+  CUSR: "Customs released",
+  CROS: "Crossed (transshipment)",
+  DLVR: "Delivered to consignee"
+};
+const DCSA_TRANSPORT_EVENT_CODES = {
+  ARRI: "Arrived at location",
+  DEPA: "Departed from location",
+  OMIT: "Port/location omitted from schedule"
+};
+const DCSA_EVENT_CLASSIFIERS = {
+  ACT: "Actual (event has occurred)",
+  PLN: "Planned",
+  EST: "Estimated"
+};
+export {
+  DCSA_EQUIPMENT_EVENT_CODES,
+  DCSA_EVENT_CLASSIFIERS,
+  DCSA_TRANSPORT_EVENT_CODES,
+  isSignificantMilestone,
+  mapDcsaEventToWebhookType
+};
+//# sourceMappingURL=dcsa-event-mapping.js.map

package/dist/modules/shipment_tracking/lib/dcsa-event-mapping.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/dcsa-event-mapping.ts"],
+  "sourcesContent": ["import type { TrackingEventType, TrackingEventClassifierCode } from '../data/entities'\n\n/**\n * DCSA Track & Trace Event Code Mapping\n *\n * Maps DCSA standard event codes to internal webhook event types.\n * Reference: DCSA T&T v3.0 specification\n *\n * Event Types:\n * - TRANSPORT: Vessel/transport movement events (ARRI, DEPA, OMIT)\n * - EQUIPMENT: Container handling events (LOAD, DISC, GTIN, GTOT, etc.)\n * - SHIPMENT: Document lifecycle events (not typically from carrier tracking)\n *\n * Event Classifiers:\n * - ACT: Actual (event has happened)\n * - PLN: Planned\n * - EST: Estimated\n */\n\nexport type DcsaWebhookEventType =\n  // Transport events\n  | 'shipment_tracking.transport.departed'\n  | 'shipment_tracking.transport.arrived'\n  | 'shipment_tracking.transport.eta_updated'\n  | 'shipment_tracking.transport.etd_updated'\n  | 'shipment_tracking.transport.omitted'\n  // Equipment events\n  | 'shipment_tracking.equipment.loaded'\n  | 'shipment_tracking.equipment.discharged'\n  | 'shipment_tracking.equipment.gate_in'\n  | 'shipment_tracking.equipment.gate_out'\n  | 'shipment_tracking.equipment.available_pickup'\n  | 'shipment_tracking.equipment.customs_released'\n  | 'shipment_tracking.equipment.inspected'\n  // Shipment lifecycle\n  | 'shipment_tracking.shipment.booked'\n  | 'shipment_tracking.shipment.delivered'\n  // Generic fallback\n  | 'shipment_tracking.tracking_event.created'\n\nexport type EventMappingInput = {\n  eventType: TrackingEventType\n  eventCode: string\n  eventClassifierCode?: TrackingEventClassifierCode | null\n}\n\n/**\n * Maps a DCSA cargo event to the appropriate webhook event type.\n *\n * @param input - The cargo event details from carrier API\n * @returns The internal webhook event type to emit\n */\nexport function mapDcsaEventToWebhookType(input: EventMappingInput): DcsaWebhookEventType {\n  const { eventType, eventCode, eventClassifierCode } = input\n  const code = eventCode.toUpperCase()\n  const isActual = eventClassifierCode === 'ACT'\n  const isEstimatedOrPlanned = eventClassifierCode === 'EST' || eventClassifierCode === 'PLN'\n\n  // \u2500\u2500\u2500 Transport Events \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  if (eventType === 'TRANSPORT') {\n    switch (code) {\n      case 'DEPA': // Departure\n        if (isActual) return 'shipment_tracking.transport.departed'\n        if (isEstimatedOrPlanned) return 'shipment_tracking.transport.etd_updated'\n        return 'shipment_tracking.transport.etd_updated' // Default to ETD update\n      case 'ARRI': // Arrival\n        if (isActual) return 'shipment_tracking.transport.arrived'\n        if (isEstimatedOrPlanned) return 'shipment_tracking.transport.eta_updated'\n        return 'shipment_tracking.transport.eta_updated' // Default to ETA update\n      case 'OMIT': // Port omitted\n        return 'shipment_tracking.transport.omitted'\n    }\n  }\n\n  // \u2500\u2500\u2500 Equipment Events \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  if (eventType === 'EQUIPMENT') {\n    switch (code) {\n      // Loading/Discharge\n      case 'LOAD': // Loaded onto vessel\n        return 'shipment_tracking.equipment.loaded'\n      case 'DISC': // Discharged from vessel\n        return 'shipment_tracking.equipment.discharged'\n\n      // Gate movements\n      case 'GTIN': // Gate in\n        return 'shipment_tracking.equipment.gate_in'\n      case 'GTOT': // Gate out (terminal)\n        return 'shipment_tracking.equipment.gate_out'\n\n      // Availability\n      case 'AVPU': // Available for pick-up\n        return 'shipment_tracking.equipment.available_pickup'\n      case 'AVDO': // Available for drop-off (less common, map to gate_in context)\n        return 'shipment_tracking.equipment.gate_in'\n\n      // Customs\n      case 'CUSR': // Customs released\n        return 'shipment_tracking.equipment.customs_released'\n      case 'CUSS': // Customs selected for scan\n      case 'CUSI': // Customs selected for inspection\n        return 'shipment_tracking.equipment.inspected'\n\n      // Inspection\n      case 'INSP': // Inspected\n        return 'shipment_tracking.equipment.inspected'\n\n      // Delivery\n      case 'DLVR': // Delivered\n        if (isActual) return 'shipment_tracking.shipment.delivered'\n        break\n\n      // Pick-up/Drop-off (physical movement)\n      case 'PICK': // Pick-up\n        return 'shipment_tracking.equipment.gate_out'\n      case 'DROP': // Drop-off\n        return 'shipment_tracking.equipment.gate_in'\n\n      // Stuffing/Stripping\n      case 'STUF': // Stuffed (cargo loaded into container)\n      case 'STRP': // Stripped (cargo unloaded from container)\n        // These are container content events, map to generic\n        break\n\n      // Sealing\n      case 'RSEA': // Resealed\n      case 'RMVD': // Seal removed\n        // Seal events, map to generic\n        break\n\n      // Transshipment crossing\n      case 'CROS': // Crossed (transshipment)\n        // Map to discharge as it indicates container moved\n        return 'shipment_tracking.equipment.discharged'\n    }\n  }\n\n  // \u2500\u2500\u2500 Shipment Events \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  if (eventType === 'SHIPMENT') {\n    // Shipment events are typically document-related (booking, BL issuance)\n    // These come from different APIs, not container tracking\n    // Map common booking-related codes\n    switch (code) {\n      case 'CONF': // Confirmed\n      case 'BOOK': // Booked (non-standard but common)\n        return 'shipment_tracking.shipment.booked'\n    }\n  }\n\n  // \u2500\u2500\u2500 Fallback \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  return 'shipment_tracking.tracking_event.created'\n}\n\n/**\n * Determines if a tracking event represents a significant milestone\n * that warrants a specific webhook event (vs generic tracking_event.created).\n */\nexport function isSignificantMilestone(input: EventMappingInput): boolean {\n  const webhookType = mapDcsaEventToWebhookType(input)\n  return webhookType !== 'shipment_tracking.tracking_event.created'\n}\n\n/**\n * DCSA Equipment Event Type Codes reference\n */\nexport const DCSA_EQUIPMENT_EVENT_CODES = {\n  LOAD: 'Loaded onto transport',\n  DISC: 'Discharged from transport',\n  GTIN: 'Gated in (entered facility)',\n  GTOT: 'Gated out (terminal)',\n  STUF: 'Stuffed (cargo loaded into container)',\n  STRP: 'Stripped (cargo removed from container)',\n  PICK: 'Pick-up by consignee/trucker',\n  DROP: 'Drop-off at facility',\n  INSP: 'Inspected',\n  RSEA: 'Resealed',\n  RMVD: 'Seal removed',\n  AVPU: 'Available for pick-up',\n  AVDO: 'Available for drop-off',\n  CUSS: 'Customs selected for scan',\n  CUSI: 'Customs selected for inspection',\n  CUSR: 'Customs released',\n  CROS: 'Crossed (transshipment)',\n  DLVR: 'Delivered to consignee',\n} as const\n\n/**\n * DCSA Transport Event Type Codes reference\n */\nexport const DCSA_TRANSPORT_EVENT_CODES = {\n  ARRI: 'Arrived at location',\n  DEPA: 'Departed from location',\n  OMIT: 'Port/location omitted from schedule',\n} as const\n\n/**\n * DCSA Event Classifier Codes reference\n */\nexport const DCSA_EVENT_CLASSIFIERS = {\n  ACT: 'Actual (event has occurred)',\n  PLN: 'Planned',\n  EST: 'Estimated',\n} as const\n"],
+  "mappings": "AAoDO,SAAS,0BAA0B,OAAgD;AACxF,QAAM,EAAE,WAAW,WAAW,oBAAoB,IAAI;AACtD,QAAM,OAAO,UAAU,YAAY;AACnC,QAAM,WAAW,wBAAwB;AACzC,QAAM,uBAAuB,wBAAwB,SAAS,wBAAwB;AAGtF,MAAI,cAAc,aAAa;AAC7B,YAAQ,MAAM;AAAA,MACZ,KAAK;AACH,YAAI,SAAU,QAAO;AACrB,YAAI,qBAAsB,QAAO;AACjC,eAAO;AAAA;AAAA,MACT,KAAK;AACH,YAAI,SAAU,QAAO;AACrB,YAAI,qBAAsB,QAAO;AACjC,eAAO;AAAA;AAAA,MACT,KAAK;AACH,eAAO;AAAA,IACX;AAAA,EACF;AAGA,MAAI,cAAc,aAAa;AAC7B,YAAQ,MAAM;AAAA;AAAA,MAEZ,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA;AAAA,MAGT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA;AAAA,MAGT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA;AAAA,MAGT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AAAA;AAAA,MACL,KAAK;AACH,eAAO;AAAA;AAAA,MAGT,KAAK;AACH,eAAO;AAAA;AAAA,MAGT,KAAK;AACH,YAAI,SAAU,QAAO;AACrB;AAAA;AAAA,MAGF,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA;AAAA,MAGT,KAAK;AAAA;AAAA,MACL,KAAK;AAEH;AAAA;AAAA,MAGF,KAAK;AAAA;AAAA,MACL,KAAK;AAEH;AAAA;AAAA,MAGF,KAAK;AAEH,eAAO;AAAA,IACX;AAAA,EACF;AAGA,MAAI,cAAc,YAAY;AAI5B,YAAQ,MAAM;AAAA,MACZ,KAAK;AAAA;AAAA,MACL,KAAK;AACH,eAAO;AAAA,IACX;AAAA,EACF;AAGA,SAAO;AACT;AAMO,SAAS,uBAAuB,OAAmC;AACxE,QAAM,cAAc,0BAA0B,KAAK;AACnD,SAAO,gBAAgB;AACzB;AAKO,MAAM,6BAA6B;AAAA,EACxC,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AACR;AAKO,MAAM,6BAA6B;AAAA,EACxC,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AACR;AAKO,MAAM,yBAAyB;AAAA,EACpC,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AACP;",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/dcsa-event-parser.js

@@ -0,0 +1,112 @@
+import crypto from "node:crypto";
+function parseCoordinate(value) {
+  if (value == null) return null;
+  if (typeof value === "number") return Number.isNaN(value) ? null : value;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed === "") return null;
+    const parsed = parseFloat(trimmed);
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  return null;
+}
+function extractDcsaEventArray(data) {
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === "object" && "events" in data && Array.isArray(data.events)) {
+    return data.events;
+  }
+  return [];
+}
+function parseDcsaEvents(data, _carrierName) {
+  const events = extractDcsaEventArray(data);
+  return events.map((event) => {
+    const metadata = event.metadata;
+    const payload = event.payload;
+    const effectiveEvent = payload ?? event;
+    const transportCall = effectiveEvent.transportCall;
+    const vessel = transportCall?.vessel;
+    const location = effectiveEvent.eventLocation ?? transportCall?.location;
+    const geoLocation = location?.geoLocation;
+    const address = location?.address;
+    const publisher = metadata?.publisher ?? event.publisher;
+    const sourceEventId = metadata?.eventID ?? event.eventID ?? event.eventId ?? crypto.randomUUID();
+    const eventType = metadata?.eventType ?? event.eventType;
+    const eventCode = effectiveEvent.equipmentEventTypeCode ?? effectiveEvent.transportEventTypeCode ?? effectiveEvent.shipmentEventTypeCode;
+    const eventClassifierCode = effectiveEvent.eventClassifierCode ?? null;
+    const eventDateTime = new Date(effectiveEvent.eventDateTime ?? event.eventDateTime);
+    const rawDocRefs = effectiveEvent.relatedDocumentReferences ?? effectiveEvent.documentReferences;
+    const relatedDocumentReferences = rawDocRefs?.map((ref) => ({
+      type: ref.type ?? ref.documentReferenceType,
+      value: ref.value ?? ref.documentReferenceValue
+    })) ?? null;
+    const rawSeals = effectiveEvent.seals;
+    const seals = rawSeals?.map((seal) => ({
+      number: seal.sealNumber ?? seal.number,
+      source: seal.sealSource ?? seal.source ?? null,
+      type: seal.sealType ?? seal.type ?? null
+    })) ?? null;
+    const eventCreatedDateTimeRaw = metadata?.eventCreatedDateTime ?? event.eventCreatedDateTime;
+    const eventCreatedDateTime = eventCreatedDateTimeRaw ? new Date(eventCreatedDateTimeRaw) : null;
+    return {
+      // ─── Event Source ──────────────────────────────────────────────
+      source: "dcsa",
+      sourceEventId,
+      // ─── Core Event Fields ─────────────────────────────────────────
+      eventType,
+      eventCode,
+      eventClassifierCode,
+      eventDateTime,
+      eventDateTimeOffset: null,
+      // Not typically in DCSA response, derived from datetime
+      description: effectiveEvent.description ?? null,
+      rawData: event,
+      // ─── Equipment Fields ──────────────────────────────────────────
+      equipmentReference: effectiveEvent.equipmentReference ?? null,
+      isoEquipmentCode: effectiveEvent.ISOEquipmentCode ?? null,
+      emptyIndicatorCode: effectiveEvent.emptyIndicatorCode ?? null,
+      isTransshipmentMove: effectiveEvent.isTransshipmentMove ?? null,
+      // ─── Location Fields ───────────────────────────────────────────
+      locationName: location?.locationName ?? null,
+      locationUnlocode: location?.UNLocationCode ?? location?.unLocationCode ?? transportCall?.UNLocationCode ?? transportCall?.unLocationCode ?? null,
+      locationCountry: address?.country ?? null,
+      // Facility code - transportCall has priority (where most carriers put it), then location
+      facilityCode: transportCall?.facilityCode ?? location?.facilityCode ?? null,
+      facilityCodeListProvider: transportCall?.facilityCodeListProvider ?? location?.facilityCodeListProvider ?? null,
+      facilityTypeCode: transportCall?.facilityTypeCode ?? effectiveEvent.facilityTypeCode ?? location?.facilityTypeCode ?? null,
+      // Address from otherFacility (full address string from DCSA)
+      facilityAddress: transportCall?.otherFacility ?? null,
+      // Coordinates - check location directly (as strings), then geoLocation nested
+      latitude: parseCoordinate(location?.latitude) ?? parseCoordinate(geoLocation?.latitude),
+      longitude: parseCoordinate(location?.longitude) ?? parseCoordinate(geoLocation?.longitude),
+      // ─── Transport Call Fields ─────────────────────────────────────
+      transportCallReference: transportCall?.transportCallReference ?? null,
+      modeOfTransport: transportCall?.modeOfTransport ?? null,
+      vesselName: vessel?.vesselName ?? vessel?.name ?? null,
+      vesselImo: vessel?.vesselIMONumber ?? null,
+      voyageNumber: transportCall?.carrierExportVoyageNumber ?? transportCall?.exportVoyageNumber ?? transportCall?.importVoyageNumber ?? transportCall?.voyageNumber ?? vessel?.voyage ?? null,
+      carrierServiceCode: transportCall?.carrierServiceCode ?? null,
+      carrierExportVoyageNumber: transportCall?.carrierExportVoyageNumber ?? transportCall?.exportVoyageNumber ?? null,
+      carrierImportVoyageNumber: transportCall?.carrierImportVoyageNumber ?? transportCall?.importVoyageNumber ?? null,
+      universalServiceReference: transportCall?.universalServiceReference ?? null,
+      universalExportVoyageReference: transportCall?.universalExportVoyageReference ?? null,
+      universalImportVoyageReference: transportCall?.universalImportVoyageReference ?? null,
+      portVisitReference: transportCall?.portVisitReference ?? null,
+      // ─── Document References ───────────────────────────────────────
+      relatedDocumentReferences,
+      // ─── Metadata Fields ───────────────────────────────────────────
+      eventCreatedDateTime,
+      retractedEventId: metadata?.retractedEventID ?? null,
+      publisherName: publisher?.partyName ?? _carrierName,
+      publisherRole: metadata?.publisherRole ?? event.publisherRole ?? null,
+      // ─── Additional Event Fields ───────────────────────────────────
+      delayReasonCode: effectiveEvent.delayReasonCode ?? null,
+      changeRemark: effectiveEvent.changeRemark ?? null,
+      seals
+    };
+  });
+}
+export {
+  extractDcsaEventArray,
+  parseDcsaEvents
+};
+//# sourceMappingURL=dcsa-event-parser.js.map

package/dist/modules/shipment_tracking/lib/dcsa-event-parser.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/dcsa-event-parser.ts"],
+  "sourcesContent": ["import crypto from 'node:crypto'\nimport type { CarrierFetchedEvent, DocumentReference, SealInfo } from './carrier-adapter'\nimport type { TrackingEventType, TrackingEventClassifierCode } from '../data/entities'\n\ntype RawDcsaEvent = Record<string, unknown>\n\n/**\n * Parse coordinate value - handles both number and string formats from DCSA APIs.\n * Some carriers return coordinates as strings (e.g., \"54.381628\"), others as numbers.\n */\nfunction parseCoordinate(value: unknown): number | null {\n  if (value == null) return null\n  if (typeof value === 'number') return Number.isNaN(value) ? null : value\n  if (typeof value === 'string') {\n    const trimmed = value.trim()\n    if (trimmed === '') return null\n    const parsed = parseFloat(trimmed)\n    return Number.isNaN(parsed) ? null : parsed\n  }\n  return null\n}\n\ntype DcsaResponseShape =\n  | { events: RawDcsaEvent[] }\n  | RawDcsaEvent[]\n\nexport function extractDcsaEventArray(data: unknown): RawDcsaEvent[] {\n  if (Array.isArray(data)) return data\n  if (data && typeof data === 'object' && 'events' in data && Array.isArray((data as Record<string, unknown>).events)) {\n    return (data as { events: RawDcsaEvent[] }).events\n  }\n  return []\n}\n\n/**\n * Parses DCSA T&T v3.0 events into normalized CarrierFetchedEvent objects.\n * Handles both flat event structure and nested metadata/payload structure.\n */\nexport function parseDcsaEvents(data: DcsaResponseShape, _carrierName: string): CarrierFetchedEvent[] {\n  const events = extractDcsaEventArray(data)\n\n  return events.map((event) => {\n    // DCSA v3.0 can have nested metadata/payload or flat structure\n    const metadata = event.metadata as Record<string, unknown> | undefined\n    const payload = event.payload as Record<string, unknown> | undefined\n    const effectiveEvent = payload ?? event // Use payload if present, otherwise use flat event\n\n    // Extract nested objects\n    const transportCall = effectiveEvent.transportCall as Record<string, unknown> | undefined\n    const vessel = transportCall?.vessel as Record<string, unknown> | undefined\n    const location = (effectiveEvent.eventLocation ??\n      transportCall?.location) as Record<string, unknown> | undefined\n    const geoLocation = location?.geoLocation as Record<string, unknown> | undefined\n    const address = location?.address as Record<string, unknown> | undefined\n    const publisher = (metadata?.publisher ?? event.publisher) as Record<string, unknown> | undefined\n\n    // \u2500\u2500\u2500 Event Source \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    const sourceEventId = (metadata?.eventID ?? event.eventID ?? event.eventId ?? crypto.randomUUID()) as string\n\n    // \u2500\u2500\u2500 Core Event Fields \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    const eventType = (metadata?.eventType ?? event.eventType) as TrackingEventType\n    const eventCode = (effectiveEvent.equipmentEventTypeCode ??\n      effectiveEvent.transportEventTypeCode ??\n      effectiveEvent.shipmentEventTypeCode) as string\n    const eventClassifierCode = (effectiveEvent.eventClassifierCode ?? null) as TrackingEventClassifierCode | null\n    const eventDateTime = new Date((effectiveEvent.eventDateTime ?? event.eventDateTime) as string)\n\n    // \u2500\u2500\u2500 Document References \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    const rawDocRefs = (effectiveEvent.relatedDocumentReferences ?? effectiveEvent.documentReferences) as Array<Record<string, unknown>> | undefined\n    const relatedDocumentReferences: DocumentReference[] | null = rawDocRefs?.map((ref) => ({\n      type: (ref.type ?? ref.documentReferenceType) as string,\n      value: (ref.value ?? ref.documentReferenceValue) as string,\n    })) ?? null\n\n    // \u2500\u2500\u2500 Seals \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\u2500\u2500\n    const rawSeals = effectiveEvent.seals as Array<Record<string, unknown>> | undefined\n    const seals: SealInfo[] | null = rawSeals?.map((seal) => ({\n      number: (seal.sealNumber ?? seal.number) as string,\n      source: (seal.sealSource ?? seal.source) as string | null ?? null,\n      type: (seal.sealType ?? seal.type) as string | null ?? null,\n    })) ?? null\n\n    // \u2500\u2500\u2500 Event Created DateTime \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    const eventCreatedDateTimeRaw = metadata?.eventCreatedDateTime ?? event.eventCreatedDateTime\n    const eventCreatedDateTime = eventCreatedDateTimeRaw\n      ? new Date(eventCreatedDateTimeRaw as string)\n      : null\n\n    return {\n      // \u2500\u2500\u2500 Event Source \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      source: 'dcsa' as const,\n      sourceEventId,\n\n      // \u2500\u2500\u2500 Core Event Fields \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      eventType,\n      eventCode,\n      eventClassifierCode,\n      eventDateTime,\n      eventDateTimeOffset: null, // Not typically in DCSA response, derived from datetime\n      description: (effectiveEvent.description as string) ?? null,\n      rawData: event,\n\n      // \u2500\u2500\u2500 Equipment Fields \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      equipmentReference: (effectiveEvent.equipmentReference as string) ?? null,\n      isoEquipmentCode: (effectiveEvent.ISOEquipmentCode as string) ?? null,\n      emptyIndicatorCode: (effectiveEvent.emptyIndicatorCode as 'EMPTY' | 'LADEN') ?? null,\n      isTransshipmentMove: (effectiveEvent.isTransshipmentMove as boolean) ?? null,\n\n      // \u2500\u2500\u2500 Location Fields \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      locationName: (location?.locationName as string) ?? null,\n      locationUnlocode: ((location?.UNLocationCode ?? location?.unLocationCode ?? \n                          transportCall?.UNLocationCode ?? transportCall?.unLocationCode) as string) ?? null,\n      locationCountry: (address?.country as string) ?? null,\n      \n      // Facility code - transportCall has priority (where most carriers put it), then location\n      facilityCode: ((transportCall?.facilityCode ?? location?.facilityCode) as string) ?? null,\n      facilityCodeListProvider: ((transportCall?.facilityCodeListProvider ?? \n                                  location?.facilityCodeListProvider) as 'SMDG' | 'BIC') ?? null,\n      facilityTypeCode: ((transportCall?.facilityTypeCode ?? effectiveEvent.facilityTypeCode ?? \n                          location?.facilityTypeCode) as string) ?? null,\n      \n      // Address from otherFacility (full address string from DCSA)\n      facilityAddress: (transportCall?.otherFacility as string) ?? null,\n      \n      // Coordinates - check location directly (as strings), then geoLocation nested\n      latitude: parseCoordinate(location?.latitude) ?? parseCoordinate(geoLocation?.latitude),\n      longitude: parseCoordinate(location?.longitude) ?? parseCoordinate(geoLocation?.longitude),\n\n      // \u2500\u2500\u2500 Transport Call Fields \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      transportCallReference: (transportCall?.transportCallReference as string) ?? null,\n      modeOfTransport: (transportCall?.modeOfTransport as 'VESSEL' | 'RAIL' | 'TRUCK' | 'BARGE') ?? null,\n      vesselName: ((vessel?.vesselName ?? vessel?.name) as string) ?? null,\n      vesselImo: (vessel?.vesselIMONumber as string) ?? null,\n      voyageNumber: (transportCall?.carrierExportVoyageNumber as string) ??\n        (transportCall?.exportVoyageNumber as string) ??\n        (transportCall?.importVoyageNumber as string) ??\n        (transportCall?.voyageNumber as string) ??\n        (vessel?.voyage as string) ?? null,\n      carrierServiceCode: (transportCall?.carrierServiceCode as string) ?? null,\n      carrierExportVoyageNumber: ((transportCall?.carrierExportVoyageNumber ?? transportCall?.exportVoyageNumber) as string) ?? null,\n      carrierImportVoyageNumber: ((transportCall?.carrierImportVoyageNumber ?? transportCall?.importVoyageNumber) as string) ?? null,\n      universalServiceReference: (transportCall?.universalServiceReference as string) ?? null,\n      universalExportVoyageReference: (transportCall?.universalExportVoyageReference as string) ?? null,\n      universalImportVoyageReference: (transportCall?.universalImportVoyageReference as string) ?? null,\n      portVisitReference: (transportCall?.portVisitReference as string) ?? null,\n\n      // \u2500\u2500\u2500 Document References \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      relatedDocumentReferences,\n\n      // \u2500\u2500\u2500 Metadata Fields \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      eventCreatedDateTime,\n      retractedEventId: (metadata?.retractedEventID as string) ?? null,\n      publisherName: (publisher?.partyName as string) ?? _carrierName,\n      publisherRole: (metadata?.publisherRole as string) ??\n        (event.publisherRole as string) ?? null,\n\n      // \u2500\u2500\u2500 Additional Event Fields \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      delayReasonCode: (effectiveEvent.delayReasonCode as string) ?? null,\n      changeRemark: (effectiveEvent.changeRemark as string) ?? null,\n      seals,\n    }\n  })\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/dcsa-params.js

@@ -0,0 +1,16 @@
+function buildDcsaQueryParams(referenceValue, referenceType) {
+  switch (referenceType) {
+    case "container":
+      return `equipmentReference=${encodeURIComponent(referenceValue)}`;
+    case "booking":
+      return `carrierBookingReference=${encodeURIComponent(referenceValue)}`;
+    case "bol":
+      return `transportDocumentReference=${encodeURIComponent(referenceValue)}`;
+    default:
+      return `transportDocumentReference=${encodeURIComponent(referenceValue)}`;
+  }
+}
+export {
+  buildDcsaQueryParams
+};
+//# sourceMappingURL=dcsa-params.js.map

package/dist/modules/shipment_tracking/lib/dcsa-params.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/dcsa-params.ts"],
+  "sourcesContent": ["import type { TrackingReferenceType } from '../data/entities'\n\nexport function buildDcsaQueryParams(referenceValue: string, referenceType: TrackingReferenceType): string {\n  switch (referenceType) {\n    case 'container':\n      return `equipmentReference=${encodeURIComponent(referenceValue)}`\n    case 'booking':\n      return `carrierBookingReference=${encodeURIComponent(referenceValue)}`\n    case 'bol':\n      return `transportDocumentReference=${encodeURIComponent(referenceValue)}`\n    default:\n      return `transportDocumentReference=${encodeURIComponent(referenceValue)}`\n  }\n}\n"],
+  "mappings": "AAEO,SAAS,qBAAqB,gBAAwB,eAA8C;AACzG,UAAQ,eAAe;AAAA,IACrB,KAAK;AACH,aAAO,sBAAsB,mBAAmB,cAAc,CAAC;AAAA,IACjE,KAAK;AACH,aAAO,2BAA2B,mBAAmB,cAAc,CAAC;AAAA,IACtE,KAAK;AACH,aAAO,8BAA8B,mBAAmB,cAAc,CAAC;AAAA,IACzE;AACE,aAAO,8BAA8B,mBAAmB,cAAc,CAAC;AAAA,EAC3E;AACF;",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/empty-return.js

@@ -0,0 +1,48 @@
+const STALE_AFTER_ARRIVAL_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1e3;
+function staleArrivalCutoff(now = /* @__PURE__ */ new Date()) {
+  return new Date(now.getTime() - STALE_AFTER_ARRIVAL_DAYS * DAY_MS);
+}
+function isEmptyGateIn(e) {
+  return e.eventType === "EQUIPMENT" && e.eventCode === "GTIN" && e.emptyIndicatorCode === "EMPTY" && e.eventClassifierCode === "ACT";
+}
+function isFinalDelivery(e) {
+  return e.eventType === "EQUIPMENT" && e.eventCode === "DLVR" && e.eventClassifierCode === "ACT";
+}
+function isContainerComplete(e) {
+  return isEmptyGateIn(e) || isFinalDelivery(e);
+}
+function allContainersComplete(events, containerNumbers) {
+  if (containerNumbers.size === 0) return false;
+  const complete = /* @__PURE__ */ new Set();
+  for (const e of events) {
+    if (e.equipmentReference && isContainerComplete(e)) complete.add(e.equipmentReference);
+  }
+  for (const c of containerNumbers) {
+    if (!complete.has(c)) return false;
+  }
+  return true;
+}
+function isDestinationArrival(e, destinationUnlocode) {
+  if (!destinationUnlocode) return false;
+  return (e.eventCode === "ARRI" || e.eventCode === "DISC") && e.eventClassifierCode === "ACT" && !!e.locationUnlocode && e.locationUnlocode.toUpperCase() === destinationUnlocode.toUpperCase();
+}
+function destinationArrivedBefore(events, destinationUnlocode, cutoff) {
+  for (const e of events) {
+    if (!isDestinationArrival(e, destinationUnlocode)) continue;
+    const t = e.eventDateTime ? new Date(e.eventDateTime).getTime() : NaN;
+    if (!Number.isNaN(t) && t <= cutoff.getTime()) return true;
+  }
+  return false;
+}
+export {
+  STALE_AFTER_ARRIVAL_DAYS,
+  allContainersComplete,
+  destinationArrivedBefore,
+  isContainerComplete,
+  isDestinationArrival,
+  isEmptyGateIn,
+  isFinalDelivery,
+  staleArrivalCutoff
+};
+//# sourceMappingURL=empty-return.js.map

package/dist/modules/shipment_tracking/lib/empty-return.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/empty-return.ts"],
+  "sourcesContent": ["/**\n * Container-journey completion detection (to stop polling a finished job).\n *\n * A container is done when the carrier reports either:\n *\n * - **Empty return** (DCSA carriers) \u2014 an actual (`ACT`) empty gate-in\n *   (`GTIN` + `emptyIndicatorCode === 'EMPTY'`). Keying on the empty flag is\n *   unambiguous: a *laden* `GTIN` is the export-origin gate-in (see\n *   `route-inference.ts`), so this can never fire at origin.\n * - **Delivered to consignee** (COSCO) \u2014 an actual `DLVR` event. COSCO never\n *   emits `GTIN`/`emptyIndicatorCode`, so it needs its own terminal signal.\n *   `DLVR` is COSCO-exclusive (no other adapter or fixture emits it), so this\n *   branch cannot prematurely stop a DCSA carrier. Note: we deliberately key on\n *   the `DLVR` *event code*, not the `DELIVERED` *status* \u2014 DCSA carriers reach\n *   `DELIVERED` via `GTOT`-at-destination (laden pickup) *before* the empty is\n *   returned, so a status-based stop would defeat the empty-return intent.\n *\n * A `TrackingJob` may cover many containers (Bill of Lading / Booking Number),\n * so a job is only complete when **every** discovered container is complete \u2014\n * never on the first. Pure helpers: no DI, no persistence.\n *\n * Backup for missing events: empty gate-in (and COSCO `DLVR`) are sometimes\n * absent from carrier feeds, so `destinationArrivedBefore` stops a job once it\n * has arrived at its destination port and `STALE_AFTER_ARRIVAL_DAYS` have passed.\n */\n\n/** Minimal event shape both a fetched and a persisted `TrackingEvent` satisfy. */\nexport type EmptyReturnEvent = {\n  eventType: string\n  eventCode: string\n  eventClassifierCode?: string | null\n  emptyIndicatorCode?: string | null\n  equipmentReference?: string | null\n  locationUnlocode?: string | null\n  eventDateTime?: Date | string | null\n}\n\n/** Buffer after destination arrival before we stop a job whose empty-return event never arrived. */\nexport const STALE_AFTER_ARRIVAL_DAYS = 30\nconst DAY_MS = 24 * 60 * 60 * 1000\n\n/** The `cutoff` for `destinationArrivedBefore`: arrivals at/before this are stale. */\nexport function staleArrivalCutoff(now: Date = new Date()): Date {\n  return new Date(now.getTime() - STALE_AFTER_ARRIVAL_DAYS * DAY_MS)\n}\n\n/** An actual empty gate-in \u2014 the empty container returned to a depot (DCSA). */\nexport function isEmptyGateIn(e: EmptyReturnEvent): boolean {\n  return (\n    e.eventType === 'EQUIPMENT' &&\n    e.eventCode === 'GTIN' &&\n    e.emptyIndicatorCode === 'EMPTY' &&\n    e.eventClassifierCode === 'ACT'\n  )\n}\n\n/** An actual delivery to consignee \u2014 COSCO's terminal signal (CS210 \u2192 DLVR). */\nexport function isFinalDelivery(e: EmptyReturnEvent): boolean {\n  return e.eventType === 'EQUIPMENT' && e.eventCode === 'DLVR' && e.eventClassifierCode === 'ACT'\n}\n\n/** A container is done when it is returned empty (DCSA) or delivered (COSCO). */\nexport function isContainerComplete(e: EmptyReturnEvent): boolean {\n  return isEmptyGateIn(e) || isFinalDelivery(e)\n}\n\n/**\n * True when the job has \u22651 discovered container and every one has completed its\n * journey (empty return or delivery), i.e. polling can stop.\n */\nexport function allContainersComplete(\n  events: readonly EmptyReturnEvent[],\n  containerNumbers: ReadonlySet<string>,\n): boolean {\n  if (containerNumbers.size === 0) return false\n  const complete = new Set<string>()\n  for (const e of events) {\n    if (e.equipmentReference && isContainerComplete(e)) complete.add(e.equipmentReference)\n  }\n  for (const c of containerNumbers) {\n    if (!complete.has(c)) return false\n  }\n  return true\n}\n\n/**\n * An actual arrival at the job's destination port \u2014 `ARRI` (transport) or `DISC`\n * (equipment), `ACT`, at the destination UNLOCODE. Destination-scoped by\n * construction: a null/unknown destination matches nothing, so the backup can\n * never fire for an in-transit shipment. Transshipment arrivals (different\n * UNLOCODE) are excluded.\n */\nexport function isDestinationArrival(\n  e: EmptyReturnEvent,\n  destinationUnlocode: string | null | undefined,\n): boolean {\n  if (!destinationUnlocode) return false\n  return (\n    (e.eventCode === 'ARRI' || e.eventCode === 'DISC') &&\n    e.eventClassifierCode === 'ACT' &&\n    !!e.locationUnlocode &&\n    e.locationUnlocode.toUpperCase() === destinationUnlocode.toUpperCase()\n  )\n}\n\n/**\n * Time-based backup: true when the shipment arrived at its destination port\n * at/before `cutoff` (i.e. long enough ago to stop even though the empty-return\n * event never arrived). Job-level \u2014 `ARRI` carries no container reference.\n */\nexport function destinationArrivedBefore(\n  events: readonly EmptyReturnEvent[],\n  destinationUnlocode: string | null | undefined,\n  cutoff: Date,\n): boolean {\n  for (const e of events) {\n    if (!isDestinationArrival(e, destinationUnlocode)) continue\n    const t = e.eventDateTime ? new Date(e.eventDateTime).getTime() : NaN\n    if (!Number.isNaN(t) && t <= cutoff.getTime()) return true\n  }\n  return false\n}\n"],
+  "mappings": "AAsCO,MAAM,2BAA2B;AACxC,MAAM,SAAS,KAAK,KAAK,KAAK;AAGvB,SAAS,mBAAmB,MAAY,oBAAI,KAAK,GAAS;AAC/D,SAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,2BAA2B,MAAM;AACnE;AAGO,SAAS,cAAc,GAA8B;AAC1D,SACE,EAAE,cAAc,eAChB,EAAE,cAAc,UAChB,EAAE,uBAAuB,WACzB,EAAE,wBAAwB;AAE9B;AAGO,SAAS,gBAAgB,GAA8B;AAC5D,SAAO,EAAE,cAAc,eAAe,EAAE,cAAc,UAAU,EAAE,wBAAwB;AAC5F;AAGO,SAAS,oBAAoB,GAA8B;AAChE,SAAO,cAAc,CAAC,KAAK,gBAAgB,CAAC;AAC9C;AAMO,SAAS,sBACd,QACA,kBACS;AACT,MAAI,iBAAiB,SAAS,EAAG,QAAO;AACxC,QAAM,WAAW,oBAAI,IAAY;AACjC,aAAW,KAAK,QAAQ;AACtB,QAAI,EAAE,sBAAsB,oBAAoB,CAAC,EAAG,UAAS,IAAI,EAAE,kBAAkB;AAAA,EACvF;AACA,aAAW,KAAK,kBAAkB;AAChC,QAAI,CAAC,SAAS,IAAI,CAAC,EAAG,QAAO;AAAA,EAC/B;AACA,SAAO;AACT;AASO,SAAS,qBACd,GACA,qBACS;AACT,MAAI,CAAC,oBAAqB,QAAO;AACjC,UACG,EAAE,cAAc,UAAU,EAAE,cAAc,WAC3C,EAAE,wBAAwB,SAC1B,CAAC,CAAC,EAAE,oBACJ,EAAE,iBAAiB,YAAY,MAAM,oBAAoB,YAAY;AAEzE;AAOO,SAAS,yBACd,QACA,qBACA,QACS;AACT,aAAW,KAAK,QAAQ;AACtB,QAAI,CAAC,qBAAqB,GAAG,mBAAmB,EAAG;AACnD,UAAM,IAAI,EAAE,gBAAgB,IAAI,KAAK,EAAE,aAAa,EAAE,QAAQ,IAAI;AAClE,QAAI,CAAC,OAAO,MAAM,CAAC,KAAK,KAAK,OAAO,QAAQ,EAAG,QAAO;AAAA,EACxD;AACA,SAAO;AACT;",
+  "names": []
+}