@freighttech/shipment-tracking 0.6.0

package/dist/modules/shipment_tracking/lib/location-overrides.js

@@ -0,0 +1,85 @@
+import { LocationOverride } from "../data/entities.js";
+async function findLocationOverride(em, match, scope) {
+  if (!match.unlocode || !match.facilityCode || !match.facilityCodeListProvider) {
+    return null;
+  }
+  const conditions = {
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    unlocode: match.unlocode.toUpperCase(),
+    facilityCode: match.facilityCode,
+    facilityCodeListProvider: match.facilityCodeListProvider,
+    isActive: true,
+    deletedAt: null
+  };
+  if (match.carrierCode) {
+    const carrierSpecific = await em.findOne(LocationOverride, {
+      ...conditions,
+      carrierCode: match.carrierCode.toUpperCase()
+    });
+    if (carrierSpecific) {
+      return carrierSpecific;
+    }
+  }
+  const globalOverride = await em.findOne(LocationOverride, {
+    ...conditions,
+    carrierCode: null
+  });
+  return globalOverride;
+}
+function applyLocationOverride(location, overrideData) {
+  const result = { ...location };
+  if (overrideData.name != null) {
+    result.name = overrideData.name;
+  }
+  if (overrideData.address !== void 0) {
+    result.address = overrideData.address;
+  }
+  if (overrideData.operatorName !== void 0) {
+    result.operatorName = overrideData.operatorName;
+  }
+  if (overrideData.countryCode !== void 0) {
+    result.countryCode = overrideData.countryCode;
+  }
+  if (overrideData.facilityTypeCode !== void 0) {
+    result.facilityTypeCode = overrideData.facilityTypeCode;
+  }
+  if (overrideData.coords !== void 0) {
+    result.coords = overrideData.coords;
+  }
+  if (overrideData.unlocode !== void 0) {
+    result.unlocode = overrideData.unlocode;
+  }
+  if (overrideData.facilityCode !== void 0) {
+    result.facilityCode = overrideData.facilityCode;
+  }
+  if (overrideData.facilityCodeListProvider !== void 0) {
+    result.facilityCodeListProvider = overrideData.facilityCodeListProvider;
+  }
+  result.source = "manual";
+  return result;
+}
+async function applyLocationOverrideIfExists(em, location, carrierCode, scope) {
+  if (!location) {
+    return null;
+  }
+  if (!location.unlocode || !location.facilityCode || !location.facilityCodeListProvider) {
+    return location;
+  }
+  const override = await findLocationOverride(em, {
+    unlocode: location.unlocode,
+    facilityCode: location.facilityCode,
+    facilityCodeListProvider: location.facilityCodeListProvider,
+    carrierCode
+  }, scope);
+  if (override) {
+    return applyLocationOverride(location, override.overrideData);
+  }
+  return location;
+}
+export {
+  applyLocationOverride,
+  applyLocationOverrideIfExists,
+  findLocationOverride
+};
+//# sourceMappingURL=location-overrides.js.map

package/dist/modules/shipment_tracking/lib/location-overrides.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/location-overrides.ts"],
+  "sourcesContent": ["/**\n * Location Override Helpers\n *\n * Provides lookup and application of location overrides for BIC/SMDG facility data.\n * Overrides allow correcting incorrect terminal/facility information from BIC API.\n */\n\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport { LocationOverride, type FacilityLocation, type FacilityCodeListProvider } from '../data/entities'\n\nexport interface LocationOverrideMatch {\n  unlocode: string\n  facilityCode: string\n  facilityCodeListProvider: FacilityCodeListProvider\n  carrierCode?: string | null\n}\n\nexport interface LocationOverrideScope {\n  organizationId: string\n  tenantId: string\n}\n\n/**\n * Finds the most specific location override for a given facility.\n *\n * Priority order:\n * 1. Carrier-specific override (carrierCode matches)\n * 2. Global override (carrierCode is null)\n *\n * @returns The override to apply, or null if no override exists\n */\nexport async function findLocationOverride(\n  em: EntityManager,\n  match: LocationOverrideMatch,\n  scope: LocationOverrideScope\n): Promise<LocationOverride | null> {\n  if (!match.unlocode || !match.facilityCode || !match.facilityCodeListProvider) {\n    return null\n  }\n\n  // Build query conditions - carrier-specific first, then global\n  const conditions: Record<string, unknown> = {\n    organizationId: scope.organizationId,\n    tenantId: scope.tenantId,\n    unlocode: match.unlocode.toUpperCase(),\n    facilityCode: match.facilityCode,\n    facilityCodeListProvider: match.facilityCodeListProvider,\n    isActive: true,\n    deletedAt: null,\n  }\n\n  // First try carrier-specific override (normalize to uppercase)\n  if (match.carrierCode) {\n    const carrierSpecific = await em.findOne(LocationOverride, {\n      ...conditions,\n      carrierCode: match.carrierCode.toUpperCase(),\n    })\n    if (carrierSpecific) {\n      return carrierSpecific\n    }\n  }\n\n  // Fall back to global override (carrierCode is null)\n  const globalOverride = await em.findOne(LocationOverride, {\n    ...conditions,\n    carrierCode: null,\n  })\n\n  return globalOverride\n}\n\n/**\n * Applies override data to a FacilityLocation.\n * Only non-null fields from the override are applied.\n * Sets source to 'manual' to indicate the data was manually overridden.\n */\nexport function applyLocationOverride(\n  location: FacilityLocation,\n  overrideData: Partial<FacilityLocation>\n): FacilityLocation {\n  const result: FacilityLocation = { ...location }\n\n  // Apply each override field if it's defined and not null\n  if (overrideData.name != null) {\n    result.name = overrideData.name\n  }\n  if (overrideData.address !== undefined) {\n    result.address = overrideData.address\n  }\n  if (overrideData.operatorName !== undefined) {\n    result.operatorName = overrideData.operatorName\n  }\n  if (overrideData.countryCode !== undefined) {\n    result.countryCode = overrideData.countryCode\n  }\n  if (overrideData.facilityTypeCode !== undefined) {\n    result.facilityTypeCode = overrideData.facilityTypeCode\n  }\n  if (overrideData.coords !== undefined) {\n    result.coords = overrideData.coords\n  }\n  // Can also override unlocode/facilityCode if needed (rare)\n  if (overrideData.unlocode !== undefined) {\n    result.unlocode = overrideData.unlocode\n  }\n  if (overrideData.facilityCode !== undefined) {\n    result.facilityCode = overrideData.facilityCode\n  }\n  if (overrideData.facilityCodeListProvider !== undefined) {\n    result.facilityCodeListProvider = overrideData.facilityCodeListProvider\n  }\n\n  // Mark as manually overridden\n  result.source = 'manual'\n\n  return result\n}\n\n/**\n * Finds and applies location override to a FacilityLocation in one step.\n * Returns the original location if no override exists.\n */\nexport async function applyLocationOverrideIfExists(\n  em: EntityManager,\n  location: FacilityLocation | null | undefined,\n  carrierCode: string | null | undefined,\n  scope: LocationOverrideScope\n): Promise<FacilityLocation | null> {\n  if (!location) {\n    return null\n  }\n\n  // Skip if location doesn't have required match fields\n  if (!location.unlocode || !location.facilityCode || !location.facilityCodeListProvider) {\n    return location\n  }\n\n  const override = await findLocationOverride(em, {\n    unlocode: location.unlocode,\n    facilityCode: location.facilityCode,\n    facilityCodeListProvider: location.facilityCodeListProvider,\n    carrierCode,\n  }, scope)\n\n  if (override) {\n    return applyLocationOverride(location, override.overrideData)\n  }\n\n  return location\n}\n"],
+  "mappings": "AAQA,SAAS,wBAA8E;AAuBvF,eAAsB,qBACpB,IACA,OACA,OACkC;AAClC,MAAI,CAAC,MAAM,YAAY,CAAC,MAAM,gBAAgB,CAAC,MAAM,0BAA0B;AAC7E,WAAO;AAAA,EACT;AAGA,QAAM,aAAsC;AAAA,IAC1C,gBAAgB,MAAM;AAAA,IACtB,UAAU,MAAM;AAAA,IAChB,UAAU,MAAM,SAAS,YAAY;AAAA,IACrC,cAAc,MAAM;AAAA,IACpB,0BAA0B,MAAM;AAAA,IAChC,UAAU;AAAA,IACV,WAAW;AAAA,EACb;AAGA,MAAI,MAAM,aAAa;AACrB,UAAM,kBAAkB,MAAM,GAAG,QAAQ,kBAAkB;AAAA,MACzD,GAAG;AAAA,MACH,aAAa,MAAM,YAAY,YAAY;AAAA,IAC7C,CAAC;AACD,QAAI,iBAAiB;AACnB,aAAO;AAAA,IACT;AAAA,EACF;AAGA,QAAM,iBAAiB,MAAM,GAAG,QAAQ,kBAAkB;AAAA,IACxD,GAAG;AAAA,IACH,aAAa;AAAA,EACf,CAAC;AAED,SAAO;AACT;AAOO,SAAS,sBACd,UACA,cACkB;AAClB,QAAM,SAA2B,EAAE,GAAG,SAAS;AAG/C,MAAI,aAAa,QAAQ,MAAM;AAC7B,WAAO,OAAO,aAAa;AAAA,EAC7B;AACA,MAAI,aAAa,YAAY,QAAW;AACtC,WAAO,UAAU,aAAa;AAAA,EAChC;AACA,MAAI,aAAa,iBAAiB,QAAW;AAC3C,WAAO,eAAe,aAAa;AAAA,EACrC;AACA,MAAI,aAAa,gBAAgB,QAAW;AAC1C,WAAO,cAAc,aAAa;AAAA,EACpC;AACA,MAAI,aAAa,qBAAqB,QAAW;AAC/C,WAAO,mBAAmB,aAAa;AAAA,EACzC;AACA,MAAI,aAAa,WAAW,QAAW;AACrC,WAAO,SAAS,aAAa;AAAA,EAC/B;AAEA,MAAI,aAAa,aAAa,QAAW;AACvC,WAAO,WAAW,aAAa;AAAA,EACjC;AACA,MAAI,aAAa,iBAAiB,QAAW;AAC3C,WAAO,eAAe,aAAa;AAAA,EACrC;AACA,MAAI,aAAa,6BAA6B,QAAW;AACvD,WAAO,2BAA2B,aAAa;AAAA,EACjD;AAGA,SAAO,SAAS;AAEhB,SAAO;AACT;AAMA,eAAsB,8BACpB,IACA,UACA,aACA,OACkC;AAClC,MAAI,CAAC,UAAU;AACb,WAAO;AAAA,EACT;AAGA,MAAI,CAAC,SAAS,YAAY,CAAC,SAAS,gBAAgB,CAAC,SAAS,0BAA0B;AACtF,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,MAAM,qBAAqB,IAAI;AAAA,IAC9C,UAAU,SAAS;AAAA,IACnB,cAAc,SAAS;AAAA,IACvB,0BAA0B,SAAS;AAAA,IACnC;AAAA,EACF,GAAG,KAAK;AAER,MAAI,UAAU;AACZ,WAAO,sBAAsB,UAAU,SAAS,YAAY;AAAA,EAC9D;AAEA,SAAO;AACT;",
+  "names": []
+}

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

@@ -0,0 +1,59 @@
+function isLocationComplete(loc) {
+  if (!loc) return false;
+  const hasName = !!loc.name && loc.name !== "Unknown";
+  const hasCoords = loc.coords?.latitude != null && loc.coords?.longitude != null;
+  const hasAddress = !!loc.address;
+  return hasName && (hasCoords || hasAddress);
+}
+function buildLocationFromEvent(event) {
+  const countryCode = event.locationCountry || (event.locationUnlocode?.length === 5 ? event.locationUnlocode.slice(0, 2) : null);
+  return {
+    name: event.locationName || event.locationUnlocode || "Unknown",
+    unlocode: event.locationUnlocode || null,
+    countryCode,
+    facilityCode: event.facilityCode || null,
+    facilityCodeListProvider: event.facilityCodeListProvider || null,
+    facilityTypeCode: event.facilityTypeCode || null,
+    address: event.facilityAddress || null,
+    coords: event.latitude != null && event.longitude != null ? { latitude: event.latitude, longitude: event.longitude } : null,
+    operatorName: null,
+    // Only populated by BIC enrichment
+    source: "dcsa"
+  };
+}
+function mergeLocationWithBicData(location, bicData) {
+  const enrichedName = bicData.name || location.name;
+  return {
+    ...location,
+    name: enrichedName,
+    address: location.address || bicData.address || null,
+    coords: location.coords || bicData.coords || null,
+    operatorName: location.operatorName || bicData.operatorName || null,
+    facilityCode: location.facilityCode || bicData.facilityCode || null,
+    facilityCodeListProvider: location.facilityCodeListProvider || bicData.facilityCodeListProvider || null,
+    source: bicData.name || bicData.address || bicData.coords ? "bic" : location.source
+  };
+}
+function createBasicLocation(nameOrUnlocode, unlocode) {
+  const actualUnlocode = unlocode || (nameOrUnlocode.length === 5 ? nameOrUnlocode : null);
+  const countryCode = actualUnlocode?.slice(0, 2) || null;
+  return {
+    name: nameOrUnlocode,
+    unlocode: actualUnlocode,
+    countryCode,
+    facilityCode: null,
+    facilityCodeListProvider: null,
+    facilityTypeCode: null,
+    address: null,
+    coords: null,
+    operatorName: null,
+    source: "manual"
+  };
+}
+export {
+  buildLocationFromEvent,
+  createBasicLocation,
+  isLocationComplete,
+  mergeLocationWithBicData
+};
+//# sourceMappingURL=location-types.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/location-types.ts"],
+  "sourcesContent": ["/**\n * Location Types for Shipment Tracking\n * \n * Rich location data combining port (UN/LOCODE) and facility/terminal details.\n * Used for Shipment origin/destination and RouteStopEntry.\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 * Rich location data for origin, destination, or transshipment points.\n * Combines port-level (UN/LOCODE) with facility-level (terminal) details.\n */\nexport interface FacilityLocation {\n  // Display name (terminal or port name)\n  name: string\n\n  // Port-level identifiers\n  unlocode: string | null          // UN/LOCODE (e.g., \"PLGDN\")\n  countryCode: string | null       // ISO 3166-1 alpha-2 (e.g., \"PL\")\n\n  // Facility/terminal identifiers (separate fields)\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\n  // Address (from DCSA otherFacility or BIC API)\n  address: string | null           // Full address string\n\n  // Coordinates\n  coords: {\n    latitude: number\n    longitude: number\n  } | null\n\n  // Operator (from BIC API enrichment only)\n  operatorName: string | null\n\n  // Source of the data\n  source: 'dcsa' | 'bic' | 'manual'\n}\n\n/**\n * Input type for building FacilityLocation from TrackingEvent data.\n */\nexport interface LocationEventInput {\n  locationName?: string | null\n  locationUnlocode?: string | null\n  locationCountry?: string | null\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}\n\n// \u2500\u2500\u2500 Helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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 if location data is \"complete enough\" to skip BIC enrichment.\n * Complete = has name AND (coords OR address)\n */\nexport function isLocationComplete(loc: Partial<FacilityLocation> | null | undefined): boolean {\n  if (!loc) return false\n  const hasName = !!loc.name && loc.name !== 'Unknown'\n  const hasCoords = loc.coords?.latitude != null && loc.coords?.longitude != null\n  const hasAddress = !!loc.address\n\n  // Complete if we have name AND (coords OR address)\n  return hasName && (hasCoords || hasAddress)\n}\n\n/**\n * Builds a FacilityLocation from TrackingEvent data.\n * Extracts country code from UN/LOCODE if not provided.\n */\nexport function buildLocationFromEvent(event: LocationEventInput): FacilityLocation {\n  // Extract country code from UN/LOCODE (first 2 chars) if not provided\n  const countryCode = event.locationCountry ||\n    (event.locationUnlocode?.length === 5 ? event.locationUnlocode.slice(0, 2) : null)\n\n  return {\n    name: event.locationName || event.locationUnlocode || 'Unknown',\n    unlocode: event.locationUnlocode || null,\n    countryCode,\n    facilityCode: event.facilityCode || null,\n    facilityCodeListProvider: event.facilityCodeListProvider || null,\n    facilityTypeCode: event.facilityTypeCode || null,\n    address: event.facilityAddress || null,\n    coords: (event.latitude != null && event.longitude != null)\n      ? { latitude: event.latitude, longitude: event.longitude }\n      : null,\n    operatorName: null, // Only populated by BIC enrichment\n    source: 'dcsa',\n  }\n}\n\n/**\n * Merges BIC enrichment data into an existing FacilityLocation.\n * BIC provides more detailed facility names (e.g., \"GDYNIA CONTAINER TERMINAL S.A.\")\n * so we prefer BIC name over generic port names from DCSA.\n */\nexport function mergeLocationWithBicData(\n  location: FacilityLocation,\n  bicData: {\n    name?: string\n    address?: string\n    coords?: { latitude: number; longitude: number }\n    operatorName?: string\n    facilityCode?: string\n    facilityCodeListProvider?: 'BIC' | 'SMDG'\n  }\n): FacilityLocation {\n  // BIC provides more descriptive terminal names, so prefer BIC name when available\n  // Only keep DCSA name if BIC doesn't provide one\n  const enrichedName = bicData.name || location.name\n\n  return {\n    ...location,\n    name: enrichedName,\n    address: location.address || bicData.address || null,\n    coords: location.coords || bicData.coords || null,\n    operatorName: location.operatorName || bicData.operatorName || null,\n    facilityCode: location.facilityCode || bicData.facilityCode || null,\n    facilityCodeListProvider: location.facilityCodeListProvider || bicData.facilityCodeListProvider || null,\n    source: bicData.name || bicData.address || bicData.coords ? 'bic' : location.source,\n  }\n}\n\n/**\n * Creates an empty/unknown FacilityLocation with just a name/unlocode.\n * Used when no event data is available but we need a location object.\n */\nexport function createBasicLocation(\n  nameOrUnlocode: string,\n  unlocode?: string | null\n): FacilityLocation {\n  const actualUnlocode = unlocode || (nameOrUnlocode.length === 5 ? nameOrUnlocode : null)\n  const countryCode = actualUnlocode?.slice(0, 2) || null\n\n  return {\n    name: nameOrUnlocode,\n    unlocode: actualUnlocode,\n    countryCode,\n    facilityCode: null,\n    facilityCodeListProvider: null,\n    facilityTypeCode: null,\n    address: null,\n    coords: null,\n    operatorName: null,\n    source: 'manual',\n  }\n}\n"],
+  "mappings": "AA+DO,SAAS,mBAAmB,KAA4D;AAC7F,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,UAAU,CAAC,CAAC,IAAI,QAAQ,IAAI,SAAS;AAC3C,QAAM,YAAY,IAAI,QAAQ,YAAY,QAAQ,IAAI,QAAQ,aAAa;AAC3E,QAAM,aAAa,CAAC,CAAC,IAAI;AAGzB,SAAO,YAAY,aAAa;AAClC;AAMO,SAAS,uBAAuB,OAA6C;AAElF,QAAM,cAAc,MAAM,oBACvB,MAAM,kBAAkB,WAAW,IAAI,MAAM,iBAAiB,MAAM,GAAG,CAAC,IAAI;AAE/E,SAAO;AAAA,IACL,MAAM,MAAM,gBAAgB,MAAM,oBAAoB;AAAA,IACtD,UAAU,MAAM,oBAAoB;AAAA,IACpC;AAAA,IACA,cAAc,MAAM,gBAAgB;AAAA,IACpC,0BAA0B,MAAM,4BAA4B;AAAA,IAC5D,kBAAkB,MAAM,oBAAoB;AAAA,IAC5C,SAAS,MAAM,mBAAmB;AAAA,IAClC,QAAS,MAAM,YAAY,QAAQ,MAAM,aAAa,OAClD,EAAE,UAAU,MAAM,UAAU,WAAW,MAAM,UAAU,IACvD;AAAA,IACJ,cAAc;AAAA;AAAA,IACd,QAAQ;AAAA,EACV;AACF;AAOO,SAAS,yBACd,UACA,SAQkB;AAGlB,QAAM,eAAe,QAAQ,QAAQ,SAAS;AAE9C,SAAO;AAAA,IACL,GAAG;AAAA,IACH,MAAM;AAAA,IACN,SAAS,SAAS,WAAW,QAAQ,WAAW;AAAA,IAChD,QAAQ,SAAS,UAAU,QAAQ,UAAU;AAAA,IAC7C,cAAc,SAAS,gBAAgB,QAAQ,gBAAgB;AAAA,IAC/D,cAAc,SAAS,gBAAgB,QAAQ,gBAAgB;AAAA,IAC/D,0BAA0B,SAAS,4BAA4B,QAAQ,4BAA4B;AAAA,IACnG,QAAQ,QAAQ,QAAQ,QAAQ,WAAW,QAAQ,SAAS,QAAQ,SAAS;AAAA,EAC/E;AACF;AAMO,SAAS,oBACd,gBACA,UACkB;AAClB,QAAM,iBAAiB,aAAa,eAAe,WAAW,IAAI,iBAAiB;AACnF,QAAM,cAAc,gBAAgB,MAAM,GAAG,CAAC,KAAK;AAEnD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU;AAAA,IACV;AAAA,IACA,cAAc;AAAA,IACd,0BAA0B;AAAA,IAC1B,kBAAkB;AAAA,IAClB,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,cAAc;AAAA,IACd,QAAQ;AAAA,EACV;AACF;",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/logger.js

@@ -0,0 +1,113 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+const MODULE_NAME = "shipment-tracking";
+const logContext = new AsyncLocalStorage();
+function emit(level, message, fields) {
+  const record = {
+    level,
+    time: (/* @__PURE__ */ new Date()).toISOString(),
+    message,
+    ...logContext.getStore(),
+    ...fields
+  };
+  const line = JSON.stringify(record);
+  if (level === "error") console.error(line);
+  else if (level === "warn") console.warn(line);
+  else console.log(line);
+}
+const logger = {
+  debug: (message, fields) => emit("debug", message, fields),
+  info: (message, fields) => emit("info", message, fields),
+  warn: (message, fields) => emit("warn", message, fields),
+  error: (message, fields) => emit("error", message, fields)
+};
+function runWithLogContext(ctx, fn) {
+  return logContext.run({ ...logContext.getStore(), ...ctx }, fn);
+}
+const tracer = trace.getTracer(MODULE_NAME);
+function withSpan(opts, fn) {
+  const attributes = Object.fromEntries(
+    Object.entries(opts.attributes ?? {}).filter(([, v]) => v !== void 0)
+  );
+  return tracer.startActiveSpan(opts.name, { attributes }, async (span) => {
+    try {
+      return await fn(span);
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: SpanStatusCode.ERROR });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+function withCarrierContext(ctx, fn) {
+  return runWithLogContext({ module: MODULE_NAME, ...ctx }, fn);
+}
+async function withCarrierApiSpan(ctx, fn) {
+  const spanName = `carrier.${ctx.carrierCode}.${ctx.operation}`;
+  logger.debug(`Starting ${ctx.operation}`, {
+    module: MODULE_NAME,
+    carrierCode: ctx.carrierCode,
+    operation: ctx.operation,
+    referenceType: ctx.referenceType
+  });
+  const startMs = Date.now();
+  return withSpan(
+    {
+      name: spanName,
+      attributes: {
+        "carrier.code": ctx.carrierCode,
+        "carrier.operation": ctx.operation,
+        module: MODULE_NAME,
+        ...ctx.referenceType && { "tracking.reference_type": ctx.referenceType }
+      }
+    },
+    async (span) => {
+      try {
+        const result = await fn(span);
+        const durationMs = Date.now() - startMs;
+        logger.info(`Completed ${ctx.operation}`, {
+          module: MODULE_NAME,
+          carrierCode: ctx.carrierCode,
+          operation: ctx.operation,
+          durationMs,
+          success: true
+        });
+        span.setAttribute("duration_ms", durationMs);
+        return result;
+      } catch (error) {
+        const durationMs = Date.now() - startMs;
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        logger.error(`Failed ${ctx.operation}`, {
+          module: MODULE_NAME,
+          carrierCode: ctx.carrierCode,
+          operation: ctx.operation,
+          durationMs,
+          success: false,
+          error: errorMessage
+        });
+        span.setAttribute("duration_ms", durationMs);
+        throw error;
+      }
+    }
+  );
+}
+function logRateLimit(ctx) {
+  const level = ctx.allowed ? "debug" : "info";
+  logger[level]("Rate limit check", {
+    module: MODULE_NAME,
+    carrierCode: ctx.carrierCode,
+    tenantId: ctx.tenantId,
+    allowed: ctx.allowed,
+    retryAfterSeconds: ctx.retryAfterSeconds
+  });
+}
+const trackingLogger = logger;
+export {
+  logRateLimit,
+  trackingLogger,
+  withCarrierApiSpan,
+  withCarrierContext
+};
+//# sourceMappingURL=logger.js.map

package/dist/modules/shipment_tracking/lib/logger.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/logger.ts"],
+  "sourcesContent": ["import { AsyncLocalStorage } from 'node:async_hooks'\nimport { trace, SpanStatusCode, type Span } from '@opentelemetry/api'\n\nconst MODULE_NAME = 'shipment-tracking'\n\n// \u2500\u2500 Inlined structured logger + tracing \u2500\u2500\u2500\u2500\u2500\u2500\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// Previously provided by `@open-mercato/logger`, which is not published to the\n// public npm registry. Reimplemented locally over `@opentelemetry/api` (already\n// a dependency) and `node:async_hooks` so this package installs from public\n// registries with no private dependency. Behaviour parity: JSON structured\n// logs that carry any active async-local context, and an OTel active span\n// wrapper that records exceptions and always ends the span.\n\ntype LogContext = Record<string, unknown>\ntype LogLevel = 'debug' | 'info' | 'warn' | 'error'\n\nconst logContext = new AsyncLocalStorage<LogContext>()\n\nfunction emit(level: LogLevel, message: string, fields?: LogContext): void {\n  const record: LogContext = {\n    level,\n    time: new Date().toISOString(),\n    message,\n    ...logContext.getStore(),\n    ...fields,\n  }\n  const line = JSON.stringify(record)\n  if (level === 'error') console.error(line)\n  else if (level === 'warn') console.warn(line)\n  else console.log(line)\n}\n\nconst logger = {\n  debug: (message: string, fields?: LogContext) => emit('debug', message, fields),\n  info: (message: string, fields?: LogContext) => emit('info', message, fields),\n  warn: (message: string, fields?: LogContext) => emit('warn', message, fields),\n  error: (message: string, fields?: LogContext) => emit('error', message, fields),\n}\n\nfunction runWithLogContext<T>(ctx: LogContext, fn: () => T | Promise<T>): T | Promise<T> {\n  return logContext.run({ ...logContext.getStore(), ...ctx }, fn)\n}\n\nconst tracer = trace.getTracer(MODULE_NAME)\n\nfunction withSpan<T>(\n  opts: { name: string; attributes?: Record<string, string | number | boolean | undefined> },\n  fn: (span: Span) => Promise<T>,\n): Promise<T> {\n  const attributes = Object.fromEntries(\n    Object.entries(opts.attributes ?? {}).filter(([, v]) => v !== undefined),\n  ) as Record<string, string | number | boolean>\n  return tracer.startActiveSpan(opts.name, { attributes }, async (span) => {\n    try {\n      return await fn(span)\n    } catch (error) {\n      span.recordException(error as Error)\n      span.setStatus({ code: SpanStatusCode.ERROR })\n      throw error\n    } finally {\n      span.end()\n    }\n  })\n}\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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\nexport type CarrierOperation = 'authenticate' | 'fetchEvents'\n\nexport interface CarrierApiContext {\n  carrierCode: string\n  operation: CarrierOperation\n  referenceType?: string\n  referenceValue?: string\n}\n\nexport interface CarrierLogContext {\n  carrierCode: string\n  shipmentId?: string\n  trackingJobId?: string\n}\n\n/**\n * Run a function with carrier context in logs.\n * All logs within the function will include the carrier context fields.\n */\nexport function withCarrierContext<T>(\n  ctx: CarrierLogContext,\n  fn: () => T | Promise<T>,\n): T | Promise<T> {\n  return runWithLogContext({ module: MODULE_NAME, ...ctx }, fn)\n}\n\n/**\n * Run a carrier API call with OpenTelemetry span and structured logging.\n *\n * Creates a span named `carrier.{carrierCode}.{operation}` with relevant attributes.\n * Logs debug on start, info on success, error on failure.\n *\n * @example\n * ```ts\n * const events = await withCarrierApiSpan(\n *   { carrierCode: 'maersk', operation: 'fetchEvents', referenceType: 'container' },\n *   async (span) => {\n *     const response = await fetch(url, options)\n *     span.setAttribute('http.status_code', response.status)\n *     return response.json()\n *   }\n * )\n * ```\n */\nexport async function withCarrierApiSpan<T>(\n  ctx: CarrierApiContext,\n  fn: (span: Span) => Promise<T>,\n): Promise<T> {\n  const spanName = `carrier.${ctx.carrierCode}.${ctx.operation}`\n\n  logger.debug(`Starting ${ctx.operation}`, {\n    module: MODULE_NAME,\n    carrierCode: ctx.carrierCode,\n    operation: ctx.operation,\n    referenceType: ctx.referenceType,\n  })\n\n  const startMs = Date.now()\n\n  return withSpan(\n    {\n      name: spanName,\n      attributes: {\n        'carrier.code': ctx.carrierCode,\n        'carrier.operation': ctx.operation,\n        module: MODULE_NAME,\n        ...(ctx.referenceType && { 'tracking.reference_type': ctx.referenceType }),\n      },\n    },\n    async (span) => {\n      try {\n        const result = await fn(span)\n        const durationMs = Date.now() - startMs\n\n        logger.info(`Completed ${ctx.operation}`, {\n          module: MODULE_NAME,\n          carrierCode: ctx.carrierCode,\n          operation: ctx.operation,\n          durationMs,\n          success: true,\n        })\n\n        span.setAttribute('duration_ms', durationMs)\n        return result\n      } catch (error) {\n        const durationMs = Date.now() - startMs\n        const errorMessage = error instanceof Error ? error.message : 'Unknown error'\n\n        logger.error(`Failed ${ctx.operation}`, {\n          module: MODULE_NAME,\n          carrierCode: ctx.carrierCode,\n          operation: ctx.operation,\n          durationMs,\n          success: false,\n          error: errorMessage,\n        })\n\n        span.setAttribute('duration_ms', durationMs)\n        throw error\n      }\n    },\n  )\n}\n\n/**\n * Log rate limit events with structured fields.\n */\nexport function logRateLimit(ctx: {\n  carrierCode: string\n  tenantId: string\n  allowed: boolean\n  retryAfterSeconds?: number\n}): void {\n  const level = ctx.allowed ? 'debug' : 'info'\n  logger[level]('Rate limit check', {\n    module: MODULE_NAME,\n    carrierCode: ctx.carrierCode,\n    tenantId: ctx.tenantId,\n    allowed: ctx.allowed,\n    retryAfterSeconds: ctx.retryAfterSeconds,\n  })\n}\n\n/**\n * The shipment tracking logger instance.\n * Use this for general logging within the shipment-tracking module.\n */\nexport const trackingLogger = logger\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/poi-event-processor.js

@@ -0,0 +1,183 @@
+import { Shipment, TrackingEvent } from "../data/entities.js";
+import { PROXIMITY_EVENT_CODES } from "./poi-types.js";
+import { trackingLogger } from "./logger.js";
+const LOG_COMPONENT = "poi-processor";
+async function findShipmentsByVesselImo(em, vesselImo) {
+  return em.find(Shipment, {
+    vesselImo,
+    isActive: true,
+    deletedAt: null,
+    status: { $nin: ["DELIVERED"] },
+    trackingJob: { $ne: null }
+  });
+}
+function generateSourceEventId(event) {
+  const anchor = event.ata || event.atd || getPoiCode(event) || "unknown";
+  return `poi-${event.mmsi}-${event.type}-${anchor}-${event.sequenceOrder}`;
+}
+function extractEventDateTime(event) {
+  if (event.ata) {
+    return new Date(event.ata);
+  }
+  if (event.atd) {
+    return new Date(event.atd);
+  }
+  return /* @__PURE__ */ new Date();
+}
+function getPoiCode(event) {
+  return event.arrivedPoiCode || event.departedPoiCode || null;
+}
+function resolvePoiLocationName(event) {
+  if (event.type.startsWith("TERMINAL")) {
+    return event.terminalName || event.portName || event.city || null;
+  }
+  if (event.type.startsWith("PORT")) {
+    return event.city || event.portName || null;
+  }
+  return null;
+}
+function mapToOpenMercatoEventId(type) {
+  const eventMap = {
+    PORT_ARRIVAL: "shipment_tracking.poi.port_arrival",
+    PORT_PROXIMITY_ARRIVAL: "shipment_tracking.poi.port_proximity_arrival",
+    PORT_PROXIMITY_DEPARTURE: "shipment_tracking.poi.port_departure",
+    TERMINAL_ARRIVAL: "shipment_tracking.poi.terminal_arrival",
+    TERMINAL_PROXIMITY_ARRIVAL: "shipment_tracking.poi.terminal_proximity_arrival",
+    TERMINAL_PROXIMITY_DEPARTURE: "shipment_tracking.poi.terminal_departure",
+    WAYPOINT_REACHED: "shipment_tracking.poi.waypoint_reached"
+  };
+  return eventMap[type];
+}
+async function processPoiEvent(em, event) {
+  const vesselImo = String(event.shipId);
+  const shipments = await findShipmentsByVesselImo(em, vesselImo);
+  if (shipments.length === 0) {
+    trackingLogger.debug("No active shipments found for vessel IMO", {
+      component: LOG_COMPONENT,
+      mmsi: event.mmsi,
+      vesselImo,
+      eventType: event.type
+    });
+    return null;
+  }
+  return {
+    poiEvent: event,
+    vesselImo,
+    shipmentIds: shipments.map((s) => s.id),
+    eventDateTime: extractEventDateTime(event),
+    poiCode: getPoiCode(event),
+    eventCode: PROXIMITY_EVENT_CODES[event.type],
+    sourceEventId: generateSourceEventId(event)
+  };
+}
+async function isEventAlreadyProcessed(em, trackingJobId, sourceEventId) {
+  const existing = await em.findOne(TrackingEvent, {
+    trackingJob: trackingJobId,
+    source: "ais",
+    sourceEventId
+  });
+  return existing !== null;
+}
+function createTrackingEventFromPoi(processedEvent, trackingJob) {
+  const { poiEvent, eventDateTime, eventCode, sourceEventId, poiCode, vesselImo } = processedEvent;
+  const event = new TrackingEvent();
+  event.organizationId = trackingJob.organizationId;
+  event.tenantId = trackingJob.tenantId;
+  event.trackingJob = trackingJob;
+  event.source = "ais";
+  event.sourceEventId = sourceEventId;
+  event.eventType = "TRANSPORT";
+  event.eventCode = eventCode;
+  event.eventClassifierCode = "ACT";
+  event.eventDateTime = eventDateTime;
+  event.description = null;
+  event.latitude = poiEvent.lat;
+  event.longitude = poiEvent.lng;
+  event.vesselName = poiEvent.shipName;
+  event.vesselImo = vesselImo;
+  event.locationUnlocode = poiCode;
+  event.locationName = resolvePoiLocationName(poiEvent);
+  event.regionNamePl = poiEvent.regionNamePl ?? null;
+  event.regionNameEn = poiEvent.regionNameEn ?? null;
+  event.rawData = {
+    poiEventType: poiEvent.type,
+    mmsi: poiEvent.mmsi,
+    shipId: poiEvent.shipId,
+    arrivedPoiCode: poiEvent.arrivedPoiCode,
+    departedPoiCode: poiEvent.departedPoiCode,
+    distanceToPoiMeters: poiEvent.distanceToPoiMeters,
+    sequenceOrder: poiEvent.sequenceOrder,
+    // POI identity fields without dedicated columns — kept here for debugging. The resolved
+    // name lands in locationName; region names have their own columns.
+    portName: poiEvent.portName,
+    terminalName: poiEvent.terminalName,
+    city: poiEvent.city
+  };
+  return event;
+}
+async function processPoiEventBatch(em, events) {
+  const result = {
+    processed: 0,
+    matched: 0,
+    eventsCreated: 0,
+    errors: 0
+  };
+  for (const event of events) {
+    result.processed++;
+    try {
+      const processed = await processPoiEvent(em, event);
+      if (!processed) {
+        continue;
+      }
+      result.matched++;
+      for (const shipmentId of processed.shipmentIds) {
+        const shipment = await em.findOne(Shipment, { id: shipmentId }, { populate: ["trackingJob"] });
+        if (!shipment?.trackingJob) {
+          continue;
+        }
+        const alreadyProcessed = await isEventAlreadyProcessed(
+          em,
+          shipment.trackingJob.id,
+          processed.sourceEventId
+        );
+        if (alreadyProcessed) {
+          trackingLogger.debug("Event already processed", {
+            component: LOG_COMPONENT,
+            sourceEventId: processed.sourceEventId,
+            trackingJobId: shipment.trackingJob.id
+          });
+          continue;
+        }
+        const trackingEvent = createTrackingEventFromPoi(processed, shipment.trackingJob);
+        em.persist(trackingEvent);
+        result.eventsCreated++;
+      }
+    } catch (error) {
+      trackingLogger.error("Error processing POI event", {
+        component: LOG_COMPONENT,
+        mmsi: event.mmsi,
+        eventType: event.type,
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : void 0
+      });
+      result.errors++;
+    }
+  }
+  if (result.eventsCreated > 0) {
+    await em.flush();
+  }
+  return result;
+}
+export {
+  createTrackingEventFromPoi,
+  extractEventDateTime,
+  findShipmentsByVesselImo,
+  generateSourceEventId,
+  getPoiCode,
+  isEventAlreadyProcessed,
+  mapToOpenMercatoEventId,
+  processPoiEvent,
+  processPoiEventBatch,
+  resolvePoiLocationName
+};
+//# sourceMappingURL=poi-event-processor.js.map

package/dist/modules/shipment_tracking/lib/poi-event-processor.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/poi-event-processor.ts"],
+  "sourcesContent": ["/**\n * POI Event Processor\n *\n * Processes POI proximity events from AIS system and matches them\n * to tracked shipments for notification and event creation.\n */\n\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport { Shipment, TrackingEvent, TrackingJob } from '../data/entities'\nimport type { PoiProximityEvent, ProcessedPoiEvent, ProximityEventType } from './poi-types'\nimport { PROXIMITY_EVENT_CODES } from './poi-types'\nimport { trackingLogger } from './logger'\n\nconst LOG_COMPONENT = 'poi-processor'\n\n// \u2500\u2500\u2500 Shipment Matching \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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 active shipments that match the given vessel IMO.\n *\n * A shipment matches if:\n * - It has the same vesselImo\n * - It's active (not deleted, not delivered)\n * - It has an associated tracking job (tracking is enabled)\n */\nexport async function findShipmentsByVesselImo(\n  em: EntityManager,\n  vesselImo: string\n): Promise<Shipment[]> {\n  return em.find(Shipment, {\n    vesselImo,\n    isActive: true,\n    deletedAt: null,\n    status: { $nin: ['DELIVERED'] },\n    trackingJob: { $ne: null },\n  })\n}\n\n// \u2500\u2500\u2500 Event Processing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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 * Generate a deterministic source event ID for deduplication.\n *\n * Must be stable across redeliveries (nak / max_deliver retries / consumer replay),\n * so it derives only from payload fields \u2014 never the wall clock. Arrival/departure\n * events anchor on ata/atd; timeless events (e.g. WAYPOINT_REACHED) anchor on the POI code.\n *\n * Caveat: two distinct position-update batches that emit the same type + sequenceOrder\n * for the same vessel with no ata/atd and no POI code collapse to one event. Acceptable\n * for waypoints; revisit with a producer-supplied event id or JetStream msg.seq if real\n * duplicates surface.\n */\nexport function generateSourceEventId(event: PoiProximityEvent): string {\n  const anchor = event.ata || event.atd || getPoiCode(event) || 'unknown'\n  return `poi-${event.mmsi}-${event.type}-${anchor}-${event.sequenceOrder}`\n}\n\n/**\n * Extract event datetime from POI event.\n */\nexport function extractEventDateTime(event: PoiProximityEvent): Date {\n  if (event.ata) {\n    return new Date(event.ata)\n  }\n  if (event.atd) {\n    return new Date(event.atd)\n  }\n  return new Date()\n}\n\n/**\n * Get POI code from event (arrival or departure).\n */\nexport function getPoiCode(event: PoiProximityEvent): string | null {\n  return event.arrivedPoiCode || event.departedPoiCode || null\n}\n\n/**\n * Resolve the human-friendly location name for a POI event, following the producer's\n * per-type identity fallback:\n * - terminal events \u2192 terminalName \u2192 portName \u2192 city\n * - port events     \u2192 city \u2192 portName\n * - waypoint events \u2192 null (no port/terminal/city; the localized region name is used instead,\n *   stored separately in regionNamePl/regionNameEn and chosen at render time)\n *\n * Returns null when nothing usable is present, so callers fall back to the raw POI code.\n */\nexport function resolvePoiLocationName(event: PoiProximityEvent): string | null {\n  if (event.type.startsWith('TERMINAL')) {\n    return event.terminalName || event.portName || event.city || null\n  }\n  if (event.type.startsWith('PORT')) {\n    return event.city || event.portName || null\n  }\n  return null\n}\n\n/**\n * Map POI event type to Open Mercato event ID.\n */\nexport function mapToOpenMercatoEventId(type: ProximityEventType): string {\n  const eventMap: Record<ProximityEventType, string> = {\n    PORT_ARRIVAL: 'shipment_tracking.poi.port_arrival',\n    PORT_PROXIMITY_ARRIVAL: 'shipment_tracking.poi.port_proximity_arrival',\n    PORT_PROXIMITY_DEPARTURE: 'shipment_tracking.poi.port_departure',\n    TERMINAL_ARRIVAL: 'shipment_tracking.poi.terminal_arrival',\n    TERMINAL_PROXIMITY_ARRIVAL: 'shipment_tracking.poi.terminal_proximity_arrival',\n    TERMINAL_PROXIMITY_DEPARTURE: 'shipment_tracking.poi.terminal_departure',\n    WAYPOINT_REACHED: 'shipment_tracking.poi.waypoint_reached',\n  }\n  return eventMap[type]\n}\n\n/**\n * Process a POI event and match it to shipments.\n *\n * @param em - Entity manager\n * @param event - Raw POI proximity event from NATS\n * @returns Processed event with matched shipments, or null if no matches\n */\nexport async function processPoiEvent(\n  em: EntityManager,\n  event: PoiProximityEvent\n): Promise<ProcessedPoiEvent | null> {\n  // The AIS detector sets `shipId` from `ship.id`, which is the vessel IMO.\n  // Match directly against the IMO we already store on the shipment \u2014 no lookup needed.\n  const vesselImo = String(event.shipId)\n  const shipments = await findShipmentsByVesselImo(em, vesselImo)\n\n  if (shipments.length === 0) {\n    trackingLogger.debug('No active shipments found for vessel IMO', {\n      component: LOG_COMPONENT,\n      mmsi: event.mmsi,\n      vesselImo,\n      eventType: event.type,\n    })\n    return null\n  }\n\n  return {\n    poiEvent: event,\n    vesselImo,\n    shipmentIds: shipments.map((s) => s.id),\n    eventDateTime: extractEventDateTime(event),\n    poiCode: getPoiCode(event),\n    eventCode: PROXIMITY_EVENT_CODES[event.type],\n    sourceEventId: generateSourceEventId(event),\n  }\n}\n\n// \u2500\u2500\u2500 TrackingEvent Creation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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 * Check if a POI event has already been processed (deduplication).\n */\nexport async function isEventAlreadyProcessed(\n  em: EntityManager,\n  trackingJobId: string,\n  sourceEventId: string\n): Promise<boolean> {\n  const existing = await em.findOne(TrackingEvent, {\n    trackingJob: trackingJobId,\n    source: 'ais',\n    sourceEventId,\n  })\n  return existing !== null\n}\n\n/**\n * Create a TrackingEvent record from a processed POI event.\n */\nexport function createTrackingEventFromPoi(\n  processedEvent: ProcessedPoiEvent,\n  trackingJob: TrackingJob\n): TrackingEvent {\n  const { poiEvent, eventDateTime, eventCode, sourceEventId, poiCode, vesselImo } = processedEvent\n\n  const event = new TrackingEvent()\n  event.organizationId = trackingJob.organizationId\n  event.tenantId = trackingJob.tenantId\n  event.trackingJob = trackingJob\n  event.source = 'ais'\n  event.sourceEventId = sourceEventId\n  event.eventType = 'TRANSPORT'\n  event.eventCode = eventCode\n  event.eventClassifierCode = 'ACT' // Actual event\n  event.eventDateTime = eventDateTime\n  event.description = null // Labels resolved via i18n: event_codes.<CODE>\n  event.latitude = poiEvent.lat\n  event.longitude = poiEvent.lng\n  event.vesselName = poiEvent.shipName\n  // The POI producer sets shipId to the vessel IMO (that's how we matched the shipment),\n  // so persist it \u2014 route legs/maps need the IMO, not just the name.\n  event.vesselImo = vesselImo\n  event.locationUnlocode = poiCode // raw POI code (grid/LOCODE), kept as the dedup reference\n  // Friendly port/terminal name (null for waypoints, which use the localized region name below).\n  // Populating locationName also gives route extraction a real name instead of the grid code.\n  event.locationName = resolvePoiLocationName(poiEvent)\n  event.regionNamePl = poiEvent.regionNamePl ?? null\n  event.regionNameEn = poiEvent.regionNameEn ?? null\n\n  // Store raw event data for debugging\n  event.rawData = {\n    poiEventType: poiEvent.type,\n    mmsi: poiEvent.mmsi,\n    shipId: poiEvent.shipId,\n    arrivedPoiCode: poiEvent.arrivedPoiCode,\n    departedPoiCode: poiEvent.departedPoiCode,\n    distanceToPoiMeters: poiEvent.distanceToPoiMeters,\n    sequenceOrder: poiEvent.sequenceOrder,\n    // POI identity fields without dedicated columns \u2014 kept here for debugging. The resolved\n    // name lands in locationName; region names have their own columns.\n    portName: poiEvent.portName,\n    terminalName: poiEvent.terminalName,\n    city: poiEvent.city,\n  }\n\n  return event\n}\n\n// \u2500\u2500\u2500 Batch Processing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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\nexport type PoiProcessingResult = {\n  processed: number\n  matched: number\n  eventsCreated: number\n  errors: number\n}\n\n/**\n * Process a batch of POI events.\n */\nexport async function processPoiEventBatch(\n  em: EntityManager,\n  events: PoiProximityEvent[]\n): Promise<PoiProcessingResult> {\n  const result: PoiProcessingResult = {\n    processed: 0,\n    matched: 0,\n    eventsCreated: 0,\n    errors: 0,\n  }\n\n  for (const event of events) {\n    result.processed++\n\n    try {\n      const processed = await processPoiEvent(em, event)\n\n      if (!processed) {\n        continue\n      }\n\n      result.matched++\n\n      // For each matched shipment, check if we need to create events\n      for (const shipmentId of processed.shipmentIds) {\n        const shipment = await em.findOne(Shipment, { id: shipmentId }, { populate: ['trackingJob'] })\n\n        if (!shipment?.trackingJob) {\n          continue\n        }\n\n        // Check for duplicates\n        const alreadyProcessed = await isEventAlreadyProcessed(\n          em,\n          shipment.trackingJob.id,\n          processed.sourceEventId\n        )\n\n        if (alreadyProcessed) {\n          trackingLogger.debug('Event already processed', {\n            component: LOG_COMPONENT,\n            sourceEventId: processed.sourceEventId,\n            trackingJobId: shipment.trackingJob.id,\n          })\n          continue\n        }\n\n        // Create TrackingEvent\n        const trackingEvent = createTrackingEventFromPoi(processed, shipment.trackingJob)\n        em.persist(trackingEvent)\n        result.eventsCreated++\n      }\n    } catch (error) {\n      trackingLogger.error('Error processing POI event', {\n        component: LOG_COMPONENT,\n        mmsi: event.mmsi,\n        eventType: event.type,\n        error: error instanceof Error ? error.message : String(error),\n        stack: error instanceof Error ? error.stack : undefined,\n      })\n      result.errors++\n    }\n  }\n\n  if (result.eventsCreated > 0) {\n    await em.flush()\n  }\n\n  return result\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/shipment_tracking/lib/poi-nats-config.js

@@ -0,0 +1,52 @@
+import { createHash, randomUUID } from "crypto";
+function generateInstanceId() {
+  if (process.env.POI_NATS_INSTANCE_ID) {
+    return process.env.POI_NATS_INSTANCE_ID;
+  }
+  const jwtSecret = process.env.JWT_SECRET;
+  if (jwtSecret) {
+    const hash = createHash("sha256").update(jwtSecret).digest("hex");
+    return hash.substring(0, 8);
+  }
+  console.warn("[poi-nats] JWT_SECRET not set, using random instance ID (not stable across restarts)");
+  return randomUUID().split("-")[0];
+}
+const DEFAULT_RECONNECT = {
+  maxAttempts: -1,
+  // Infinite reconnect
+  initialDelayMs: 250,
+  maxDelayMs: 5e3
+};
+function loadPoiNatsConfig() {
+  const instanceId = generateInstanceId();
+  const consumerName = `shipment-tracking-poi-${instanceId}`;
+  return {
+    serverUrl: process.env.POI_NATS_URL || "nats://localhost:4222",
+    streamName: process.env.POI_NATS_STREAM || "AIS_STREAM",
+    subject: process.env.POI_NATS_SUBJECT || "ais.ship.proximity.events",
+    instanceId,
+    consumerName,
+    connectionName: `shipment-tracking-poi-${instanceId}`,
+    reconnect: DEFAULT_RECONNECT
+  };
+}
+function isPoiNatsConfigured() {
+  return !!process.env.POI_NATS_URL;
+}
+function validatePoiNatsConfig(config) {
+  if (!config.serverUrl) {
+    throw new Error("POI_NATS_URL is required");
+  }
+  if (!config.serverUrl.startsWith("nats://") && !config.serverUrl.startsWith("nats+tls://")) {
+    throw new Error("POI_NATS_URL must start with nats:// or nats+tls://");
+  }
+  if (!config.subject) {
+    throw new Error("POI_NATS_SUBJECT is required");
+  }
+}
+export {
+  isPoiNatsConfigured,
+  loadPoiNatsConfig,
+  validatePoiNatsConfig
+};
+//# sourceMappingURL=poi-nats-config.js.map

package/dist/modules/shipment_tracking/lib/poi-nats-config.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/shipment_tracking/lib/poi-nats-config.ts"],
+  "sourcesContent": ["/**\n * NATS Configuration for POI Proximity Events\n *\n * Configuration for connecting to NATS server and subscribing to\n * POI proximity events from the AIS system.\n */\n\nimport { createHash, randomUUID } from 'crypto'\n\n// \u2500\u2500\u2500 Configuration Interface \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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\nexport interface PoiNatsConfig {\n  /** NATS server URL (e.g., nats://localhost:4222) */\n  serverUrl: string\n\n  /** JetStream stream name containing POI events */\n  streamName: string\n\n  /** NATS subject for POI proximity events (filter within stream) */\n  subject: string\n\n  /** Unique instance identifier (derived from JWT_SECRET or explicit) */\n  instanceId: string\n\n  /** Durable consumer name for reliable message delivery (includes instanceId) */\n  consumerName: string\n\n  /** Connection name for debugging */\n  connectionName: string\n\n  /** Reconnect settings */\n  reconnect: {\n    /** Maximum reconnect attempts (-1 for infinite) */\n    maxAttempts: number\n    /** Initial delay between reconnects in ms */\n    initialDelayMs: number\n    /** Maximum delay between reconnects in ms */\n    maxDelayMs: number\n  }\n}\n\n// \u2500\u2500\u2500 Instance ID Generation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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 * Generate a unique instance ID for this deployment.\n *\n * Priority:\n * 1. POI_NATS_INSTANCE_ID env var (explicit override)\n * 2. Hash of JWT_SECRET (stable, unique per installation)\n * 3. Random UUID prefix (fallback for dev/testing)\n */\nfunction generateInstanceId(): string {\n  // 1. Explicit override\n  if (process.env.POI_NATS_INSTANCE_ID) {\n    return process.env.POI_NATS_INSTANCE_ID\n  }\n\n  // 2. Derive from JWT_SECRET (stable across restarts)\n  const jwtSecret = process.env.JWT_SECRET\n  if (jwtSecret) {\n    const hash = createHash('sha256').update(jwtSecret).digest('hex')\n    return hash.substring(0, 8)\n  }\n\n  // 3. Fallback to random (dev/testing only)\n  console.warn('[poi-nats] JWT_SECRET not set, using random instance ID (not stable across restarts)')\n  return randomUUID().split('-')[0]\n}\n\n// \u2500\u2500\u2500 Default Configuration \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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\nconst DEFAULT_RECONNECT = {\n  maxAttempts: -1, // Infinite reconnect\n  initialDelayMs: 250,\n  maxDelayMs: 5000,\n}\n\n// \u2500\u2500\u2500 Configuration Loader \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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 * Load POI NATS configuration from environment variables.\n *\n * Environment variables:\n * - POI_NATS_URL: NATS server URL (required to enable)\n * - POI_NATS_STREAM: JetStream stream name (default: AIS_STREAM)\n * - POI_NATS_SUBJECT: Subject filter for POI events (default: ais.ship.proximity.events)\n * - POI_NATS_INSTANCE_ID: Unique instance identifier (default: derived from JWT_SECRET)\n *\n * The consumer name is auto-generated as: shipment-tracking-poi-{instanceId}\n * This allows multiple self-hosted instances to each receive all messages independently.\n */\nexport function loadPoiNatsConfig(): PoiNatsConfig {\n  const instanceId = generateInstanceId()\n  const consumerName = `shipment-tracking-poi-${instanceId}`\n\n  return {\n    serverUrl: process.env.POI_NATS_URL || 'nats://localhost:4222',\n    streamName: process.env.POI_NATS_STREAM || 'AIS_STREAM',\n    subject: process.env.POI_NATS_SUBJECT || 'ais.ship.proximity.events',\n    instanceId,\n    consumerName,\n    connectionName: `shipment-tracking-poi-${instanceId}`,\n    reconnect: DEFAULT_RECONNECT,\n  }\n}\n\n/**\n * Check if POI NATS integration is configured.\n *\n * Returns true only if POI_NATS_URL is explicitly set.\n * When not configured, the POI subscriber will be skipped.\n */\nexport function isPoiNatsConfigured(): boolean {\n  return !!process.env.POI_NATS_URL\n}\n\n/**\n * Validate POI NATS configuration.\n *\n * @throws Error if configuration is invalid\n */\nexport function validatePoiNatsConfig(config: PoiNatsConfig): void {\n  if (!config.serverUrl) {\n    throw new Error('POI_NATS_URL is required')\n  }\n\n  if (!config.serverUrl.startsWith('nats://') && !config.serverUrl.startsWith('nats+tls://')) {\n    throw new Error('POI_NATS_URL must start with nats:// or nats+tls://')\n  }\n\n  if (!config.subject) {\n    throw new Error('POI_NATS_SUBJECT is required')\n  }\n}\n"],
+  "mappings": "AAOA,SAAS,YAAY,kBAAkB;AA4CvC,SAAS,qBAA6B;AAEpC,MAAI,QAAQ,IAAI,sBAAsB;AACpC,WAAO,QAAQ,IAAI;AAAA,EACrB;AAGA,QAAM,YAAY,QAAQ,IAAI;AAC9B,MAAI,WAAW;AACb,UAAM,OAAO,WAAW,QAAQ,EAAE,OAAO,SAAS,EAAE,OAAO,KAAK;AAChE,WAAO,KAAK,UAAU,GAAG,CAAC;AAAA,EAC5B;AAGA,UAAQ,KAAK,sFAAsF;AACnG,SAAO,WAAW,EAAE,MAAM,GAAG,EAAE,CAAC;AAClC;AAIA,MAAM,oBAAoB;AAAA,EACxB,aAAa;AAAA;AAAA,EACb,gBAAgB;AAAA,EAChB,YAAY;AACd;AAgBO,SAAS,oBAAmC;AACjD,QAAM,aAAa,mBAAmB;AACtC,QAAM,eAAe,yBAAyB,UAAU;AAExD,SAAO;AAAA,IACL,WAAW,QAAQ,IAAI,gBAAgB;AAAA,IACvC,YAAY,QAAQ,IAAI,mBAAmB;AAAA,IAC3C,SAAS,QAAQ,IAAI,oBAAoB;AAAA,IACzC;AAAA,IACA;AAAA,IACA,gBAAgB,yBAAyB,UAAU;AAAA,IACnD,WAAW;AAAA,EACb;AACF;AAQO,SAAS,sBAA+B;AAC7C,SAAO,CAAC,CAAC,QAAQ,IAAI;AACvB;AAOO,SAAS,sBAAsB,QAA6B;AACjE,MAAI,CAAC,OAAO,WAAW;AACrB,UAAM,IAAI,MAAM,0BAA0B;AAAA,EAC5C;AAEA,MAAI,CAAC,OAAO,UAAU,WAAW,SAAS,KAAK,CAAC,OAAO,UAAU,WAAW,aAAa,GAAG;AAC1F,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACvE;AAEA,MAAI,CAAC,OAAO,SAAS;AACnB,UAAM,IAAI,MAAM,8BAA8B;AAAA,EAChD;AACF;",
+  "names": []
+}