@freighttech/shipment-tracking 0.6.0

package/dist/modules/shipment_tracking/services/trackingService.js

@@ -0,0 +1,1283 @@
+import { findOneWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { Shipment, TrackingJob, TrackingEvent, CarrierConfig, BicConfig } from "../data/entities.js";
+import { ShipsGoCreditsExhaustedError, ShipsGoAuthError, ShipsGoRateLimitedError } from "../lib/shipsgo-client.js";
+import { checkRateLimit } from "../lib/rate-limiter.js";
+import { trackingLogger } from "../lib/logger.js";
+import { deriveShipmentStatus, deriveAirShipmentStatus } from "../lib/status-machine.js";
+import { extractShipmentTimes } from "../lib/time-extraction.js";
+import { generatePollSchedule, getNextPollDate } from "../lib/schedule-generator.js";
+import { mapDcsaEventToWebhookType, isSignificantMilestone } from "../lib/dcsa-event-mapping.js";
+import { inferRouteFromEvents } from "../lib/route-inference.js";
+import { allContainersComplete, destinationArrivedBefore, staleArrivalCutoff } from "../lib/empty-return.js";
+import { mergeExtractedTimestamps, getPrimaryTimestampValue } from "../lib/timestamp-utils.js";
+import { findLatestVesselInfo } from "../lib/vessel-extraction.js";
+import { extractRouteFromEvents, mapTrackingEventToEntry } from "../lib/route-extraction.js";
+import { buildLocationFromEvent, createBasicLocation, mergeLocationWithBicData, isLocationComplete } from "../lib/location-types.js";
+import { BicApiClient } from "../lib/bic-api-client.js";
+import { applyLocationOverrideIfExists } from "../lib/location-overrides.js";
+class TrackingService {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /**
+   * Creates a tracking job and immediately polls the carrier.
+   * This is the main entry point for new tracking requests.
+   * 
+   * The system will:
+   * 1. Create a TrackingJob for the given carrier and reference
+   * 2. Poll the carrier API for events
+   * 3. Auto-discover containers from EQUIPMENT events and create Shipments
+   * 4. Auto-infer origin/destination ports from events if not provided
+   * 5. Emit events for new cargo events and shipment status changes
+   */
+  async createTrackingJob(input) {
+    const em = this.deps.em();
+    const { organizationId, tenantId, carrierCode, referenceType, referenceValue, schedule } = input;
+    const provider = input.provider ?? "carrier";
+    const mode = input.mode ?? "ocean";
+    let originUnlocode = input.originUnlocode?.toUpperCase();
+    let destinationUnlocode = input.destinationUnlocode?.toUpperCase();
+    const carrierCodeLower = carrierCode.toLowerCase();
+    if (provider === "carrier" && !this.deps.carrierRegistry.has(carrierCodeLower)) {
+      throw new Error(`No adapter registered for carrier: ${carrierCode}`);
+    }
+    const existingJob = await em.findOne(TrackingJob, {
+      organizationId,
+      tenantId,
+      carrierCode: carrierCodeLower,
+      referenceType,
+      referenceValue,
+      status: { $in: ["active", "paused"] },
+      deletedAt: null
+    });
+    if (existingJob) {
+      trackingLogger.debug("TrackingJob already exists", {
+        trackingJobId: existingJob.id,
+        carrierCode: carrierCodeLower,
+        referenceType,
+        referenceValue
+      });
+      const pollResult2 = await this.pollTrackingJob(existingJob.id);
+      return {
+        trackingJobId: existingJob.id,
+        shipmentsCreated: pollResult2.shipmentsCreated,
+        newEvents: pollResult2.newEvents
+      };
+    }
+    const pollSchedule = schedule ?? generatePollSchedule({});
+    const nextPollAt = getNextPollDate(pollSchedule);
+    const trackingJob = em.create(TrackingJob, {
+      organizationId,
+      tenantId,
+      provider,
+      mode,
+      carrierCode: carrierCodeLower,
+      referenceType,
+      referenceValue,
+      originUnlocode: originUnlocode ?? null,
+      destinationUnlocode: destinationUnlocode ?? null,
+      status: "active",
+      schedule: pollSchedule,
+      nextPollAt
+    });
+    em.persist(trackingJob);
+    await em.flush();
+    trackingLogger.info("Created TrackingJob", {
+      trackingJobId: trackingJob.id,
+      carrierCode: carrierCodeLower,
+      referenceType,
+      referenceValue,
+      tenantId,
+      organizationId
+    });
+    await this.deps.eventBus.emit("shipment_tracking.tracking_job.created", {
+      id: trackingJob.id,
+      carrierCode: carrierCodeLower,
+      referenceType,
+      referenceValue,
+      tenantId,
+      organizationId
+    });
+    let pollResult = { shipmentsCreated: 0, newEvents: 0 };
+    try {
+      pollResult = await this.pollTrackingJob(trackingJob.id);
+    } catch (error) {
+      trackingLogger.error("Initial poll failed", {
+        trackingJobId: trackingJob.id,
+        carrierCode: carrierCodeLower,
+        error: error instanceof Error ? error.message : "Unknown error"
+      });
+      await this.deps.eventBus.emit("shipment_tracking.tracking_job.poll_failed", {
+        id: trackingJob.id,
+        carrierCode: carrierCodeLower,
+        error: error instanceof Error ? error.message : "Unknown error",
+        tenantId,
+        organizationId
+      });
+    }
+    return {
+      trackingJobId: trackingJob.id,
+      shipmentsCreated: pollResult.shipmentsCreated,
+      newEvents: pollResult.newEvents
+    };
+  }
+  /**
+   * Polls all active tracking jobs for a tenant/organization.
+   * Called by the scheduler for periodic re-polling.
+   */
+  async pollAllActiveJobs(tenantId, organizationId) {
+    const em = this.deps.em();
+    const filter = {
+      tenantId,
+      status: "active",
+      deletedAt: null
+    };
+    if (organizationId) {
+      filter.organizationId = organizationId;
+    }
+    const jobs = await em.find(TrackingJob, filter);
+    let polled = 0;
+    let totalNewEvents = 0;
+    let failed = 0;
+    for (const job of jobs) {
+      try {
+        const result = await this.pollTrackingJob(job.id);
+        polled++;
+        totalNewEvents += result.newEvents;
+      } catch (error) {
+        failed++;
+        trackingLogger.error("Poll failed for job", {
+          trackingJobId: job.id,
+          carrierCode: job.carrierCode,
+          error: error instanceof Error ? error.message : "Unknown error"
+        });
+        await this.deps.eventBus.emit("shipment_tracking.tracking_job.poll_failed", {
+          id: job.id,
+          carrierCode: job.carrierCode,
+          error: error instanceof Error ? error.message : "Unknown error",
+          tenantId: job.tenantId,
+          organizationId: job.organizationId
+        });
+      }
+    }
+    trackingLogger.info("Poll all completed", {
+      polled,
+      totalNewEvents,
+      failed,
+      tenantId,
+      organizationId
+    });
+    return { polled, newEvents: totalNewEvents, failed };
+  }
+  /**
+   * Polls a single tracking job:
+   * 1. Fetches events from the carrier
+   * 2. Persists new TrackingEvents
+   * 3. Auto-discovers containers and creates/updates Shipments
+   * 4. Emits events for cargo events and shipment changes
+   */
+  async pollTrackingJob(jobId) {
+    const em = this.deps.em();
+    const job = await em.findOne(TrackingJob, { id: jobId }, { populate: ["shipments"] });
+    if (!job) {
+      throw new Error(`TrackingJob not found: ${jobId}`);
+    }
+    if (job.status !== "active") {
+      return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+    }
+    const scope = { tenantId: job.tenantId, organizationId: job.organizationId };
+    let fetchedEvents;
+    let carrierResult;
+    if (job.provider === "shipsgo") {
+      const pollContext = await this.deps.shipsGoProvider.resolvePollContext(scope, job.mode);
+      const limitResult = await checkRateLimit(
+        this.deps.cacheService,
+        pollContext.rateLimitIdentity,
+        "shipsgo",
+        pollContext.rateLimit.requests,
+        pollContext.rateLimit.windowSeconds
+      );
+      if (!limitResult.allowed) {
+        trackingLogger.debug("ShipsGo rate limited, skipping poll", {
+          trackingJobId: jobId,
+          retryAfterSeconds: limitResult.retryAfterSeconds
+        });
+        return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+      }
+      try {
+        const result = await this.deps.shipsGoProvider.fetchOrRegister(job, pollContext.config);
+        fetchedEvents = result.events;
+        carrierResult = {
+          vesselName: result.vesselName,
+          vesselImo: result.vesselImo,
+          bookingNumber: result.bookingNumber,
+          bolNumber: result.bolNumber,
+          awbNumber: result.awbNumber,
+          flightNumber: result.flightNumber,
+          airlineCode: result.airlineCode,
+          airlineName: result.airlineName,
+          airStatus: result.airStatus,
+          extra: result.extra
+        };
+      } catch (error) {
+        if (error instanceof ShipsGoCreditsExhaustedError) {
+          await this.recordCreditExhaustion(em, job);
+          return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+        }
+        if (error instanceof ShipsGoRateLimitedError) {
+          const backoffMs = (error.retryAfterSeconds ?? 60) * 1e3;
+          await this.recordTransientBackoff(em, job, error.message, backoffMs);
+          return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+        }
+        if (error instanceof ShipsGoAuthError) {
+          await this.recordTransientBackoff(em, job, error.message, 30 * 60 * 1e3);
+          return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+        }
+        const message = error instanceof Error ? error.message : "Unknown ShipsGo fetch error";
+        await this.recordJobError(em, job, message);
+        return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+      }
+    } else {
+      const adapter = this.deps.carrierRegistry.get(job.carrierCode);
+      if (!adapter) {
+        await this.recordJobError(em, job, `No adapter registered for carrier: ${job.carrierCode}`);
+        return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+      }
+      const carrierConfig = await findOneWithDecryption(
+        em,
+        CarrierConfig,
+        {
+          carrierCode: job.carrierCode,
+          organizationId: job.organizationId,
+          tenantId: job.tenantId,
+          isActive: true
+        },
+        void 0,
+        scope
+      );
+      if (carrierConfig) {
+        const limitResult = await checkRateLimit(
+          this.deps.cacheService,
+          job.tenantId,
+          job.carrierCode,
+          carrierConfig.rateLimitRequests,
+          carrierConfig.rateLimitWindowSeconds
+        );
+        if (!limitResult.allowed) {
+          trackingLogger.debug("Rate limited, skipping poll", {
+            trackingJobId: jobId,
+            carrierCode: job.carrierCode,
+            retryAfterSeconds: limitResult.retryAfterSeconds
+          });
+          return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+        }
+      }
+      try {
+        const result = await adapter.fetchEvents({
+          referenceType: job.referenceType,
+          referenceValue: job.referenceValue,
+          apiEndpoint: carrierConfig?.apiEndpoint,
+          authConfig: carrierConfig?.authConfig
+        });
+        fetchedEvents = result.events;
+        carrierResult = {
+          vesselName: result.vesselName,
+          vesselImo: result.vesselImo,
+          bookingNumber: result.bookingNumber,
+          bolNumber: result.bolNumber
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown fetch error";
+        await this.recordJobError(em, job, message);
+        return { newEvents: 0, shipmentsCreated: 0, shipmentsUpdated: 0 };
+      }
+    }
+    if (fetchedEvents.length > 0 && (!job.originUnlocode || !job.destinationUnlocode)) {
+      const inferred = inferRouteFromEvents(fetchedEvents);
+      if (!job.originUnlocode && inferred.originUnlocode) {
+        job.originUnlocode = inferred.originUnlocode;
+        trackingLogger.info("Auto-inferred origin", {
+          trackingJobId: job.id,
+          carrierCode: job.carrierCode,
+          origin: inferred.originUnlocode,
+          confidence: inferred.confidence.origin
+        });
+      }
+      if (!job.destinationUnlocode && inferred.destinationUnlocode) {
+        job.destinationUnlocode = inferred.destinationUnlocode;
+        trackingLogger.info("Auto-inferred destination", {
+          trackingJobId: job.id,
+          carrierCode: job.carrierCode,
+          destination: inferred.destinationUnlocode,
+          confidence: inferred.confidence.destination
+        });
+      }
+    }
+    const existingByKey = new Map(
+      (await em.find(TrackingEvent, {
+        trackingJob: job,
+        sourceEventId: { $in: fetchedEvents.map((e) => e.sourceEventId) }
+      })).map((e) => [`${e.source}:${e.sourceEventId}`, e])
+    );
+    const newEvents = [];
+    let estRefreshed = false;
+    for (const fetched of fetchedEvents) {
+      const dedupeKey = `${fetched.source}:${fetched.sourceEventId}`;
+      const prior = existingByKey.get(dedupeKey);
+      if (prior) {
+        if (fetched.eventClassifierCode === "EST" && prior.eventDateTime.getTime() !== fetched.eventDateTime.getTime()) {
+          prior.eventDateTime = fetched.eventDateTime;
+          prior.eventDateTimeOffset = fetched.eventDateTimeOffset ?? prior.eventDateTimeOffset;
+          prior.description = fetched.description ?? prior.description;
+          prior.rawData = fetched.rawData ?? prior.rawData;
+          estRefreshed = true;
+        }
+        continue;
+      }
+      const trackingEvent = em.create(TrackingEvent, {
+        organizationId: job.organizationId,
+        tenantId: job.tenantId,
+        trackingJob: job,
+        // Source identification
+        source: fetched.source,
+        sourceEventId: fetched.sourceEventId,
+        // Core event fields
+        eventType: fetched.eventType,
+        eventCode: fetched.eventCode,
+        eventClassifierCode: fetched.eventClassifierCode,
+        eventDateTime: fetched.eventDateTime,
+        eventDateTimeOffset: fetched.eventDateTimeOffset,
+        description: fetched.description,
+        rawData: fetched.rawData,
+        // Equipment fields
+        equipmentReference: fetched.equipmentReference,
+        isoEquipmentCode: fetched.isoEquipmentCode,
+        emptyIndicatorCode: fetched.emptyIndicatorCode,
+        isTransshipmentMove: fetched.isTransshipmentMove,
+        // Location fields
+        locationName: fetched.locationName,
+        locationUnlocode: fetched.locationUnlocode,
+        locationCountry: fetched.locationCountry,
+        facilityCode: fetched.facilityCode,
+        facilityCodeListProvider: fetched.facilityCodeListProvider,
+        facilityTypeCode: fetched.facilityTypeCode,
+        facilityAddress: fetched.facilityAddress,
+        latitude: fetched.latitude,
+        longitude: fetched.longitude,
+        // Transport call fields
+        transportCallReference: fetched.transportCallReference,
+        modeOfTransport: fetched.modeOfTransport,
+        vesselName: fetched.vesselName,
+        vesselImo: fetched.vesselImo,
+        voyageNumber: fetched.voyageNumber,
+        carrierServiceCode: fetched.carrierServiceCode,
+        carrierExportVoyageNumber: fetched.carrierExportVoyageNumber,
+        carrierImportVoyageNumber: fetched.carrierImportVoyageNumber,
+        universalServiceReference: fetched.universalServiceReference,
+        universalExportVoyageReference: fetched.universalExportVoyageReference,
+        universalImportVoyageReference: fetched.universalImportVoyageReference,
+        portVisitReference: fetched.portVisitReference,
+        // Document references
+        relatedDocumentReferences: fetched.relatedDocumentReferences,
+        // Metadata fields
+        eventCreatedDateTime: fetched.eventCreatedDateTime,
+        retractedEventId: fetched.retractedEventId,
+        publisherName: fetched.publisherName,
+        publisherRole: fetched.publisherRole,
+        // Additional fields
+        delayReasonCode: fetched.delayReasonCode,
+        changeRemark: fetched.changeRemark,
+        seals: fetched.seals
+      });
+      newEvents.push(trackingEvent);
+      existingByKey.set(dedupeKey, trackingEvent);
+    }
+    if (newEvents.length > 0 || estRefreshed) {
+      await em.flush();
+    }
+    const bicConfig = await this.loadBicConfig(em, scope);
+    const { shipmentsCreated, shipmentsUpdated, allComplete } = await this.syncShipmentsFromEvents(
+      em,
+      job,
+      carrierResult,
+      bicConfig
+    );
+    job.lastPollAt = /* @__PURE__ */ new Date();
+    job.retryCount = 0;
+    await em.flush();
+    for (const event of newEvents) {
+      await this.emitTrackingEventCreated(event, job);
+    }
+    if (allComplete && job.status === "active") {
+      await this.stopJobInline(em, job, "completed");
+      trackingLogger.info("Tracking job completed (empty return / delivery, or stale after destination arrival)", {
+        trackingJobId: job.id,
+        tenantId: job.tenantId,
+        organizationId: job.organizationId
+      });
+    }
+    return { newEvents: newEvents.length, shipmentsCreated, shipmentsUpdated };
+  }
+  /**
+   * Syncs Shipments based on TrackingEvents for a job.
+   * Auto-discovers containers from equipmentReference in EQUIPMENT events.
+   * For container-based tracking (referenceType='container'), creates exactly one Shipment.
+   * For booking/BOL tracking, creates one Shipment per unique equipmentReference.
+   */
+  /**
+   * Air counterpart to syncShipmentsFromEvents. Air has no container/equipment
+   * model, so it maintains exactly one AWB-keyed Shipment (mode='air') per job,
+   * fills flight/airline metadata, and derives timestamps + status from the air
+   * movements (via deriveShipmentStateFromEvents with the ShipsGo top-level
+   * airStatus). The job auto-completes once the shipment is DELIVERED.
+   */
+  async syncAirShipmentFromEvents(em, job, carrierResult, bicConfig) {
+    const allEvents = await em.find(
+      TrackingEvent,
+      { trackingJob: job },
+      { orderBy: { eventDateTime: "asc" } }
+    );
+    const existing = await em.find(Shipment, { trackingJob: job, deletedAt: null });
+    let shipment = existing[0];
+    let shipmentsCreated = 0;
+    let isNew = false;
+    if (!shipment) {
+      shipment = em.create(Shipment, {
+        organizationId: job.organizationId,
+        tenantId: job.tenantId,
+        trackingJob: job,
+        carrierCode: job.carrierCode,
+        mode: "air",
+        awbNumber: carrierResult.awbNumber ?? job.referenceValue,
+        originLocation: job.originUnlocode ? createBasicLocation(job.originUnlocode) : null,
+        destinationLocation: job.destinationUnlocode ? createBasicLocation(job.destinationUnlocode) : null,
+        status: deriveAirShipmentStatus(carrierResult.airStatus, "PENDING")
+      });
+      em.persist(shipment);
+      shipmentsCreated = 1;
+      isNew = true;
+      trackingLogger.info("Auto-created air Shipment", {
+        shipmentId: shipment.id,
+        awbNumber: shipment.awbNumber,
+        trackingJobId: job.id
+      });
+    }
+    if (carrierResult.flightNumber) shipment.flightNumber = carrierResult.flightNumber;
+    if (carrierResult.airlineCode) shipment.airlineCode = carrierResult.airlineCode;
+    if (carrierResult.airlineName) shipment.airlineName = carrierResult.airlineName;
+    if (!shipment.awbNumber && carrierResult.awbNumber) shipment.awbNumber = carrierResult.awbNumber;
+    if (carrierResult.extra) {
+      shipment.extra = { ...shipment.extra ?? {}, ...carrierResult.extra };
+    }
+    const statusChanges = [];
+    const etaChanges = [];
+    const etdChanges = [];
+    let shipmentsUpdated = 0;
+    if (allEvents.length > 0) {
+      const result = await this.deriveShipmentStateFromEvents(
+        em,
+        shipment,
+        allEvents,
+        bicConfig,
+        carrierResult.airStatus ?? null
+      );
+      if (result.changed) {
+        shipmentsUpdated = 1;
+        if (result.statusChange) statusChanges.push({ shipment, ...result.statusChange });
+        if (result.etaChange) etaChanges.push({ shipment, ...result.etaChange });
+        if (result.etdChange) etdChanges.push({ shipment, ...result.etdChange });
+      }
+    } else if (carrierResult.airStatus) {
+      const next = deriveAirShipmentStatus(carrierResult.airStatus, shipment.status);
+      if (next !== shipment.status) {
+        statusChanges.push({ shipment, previousStatus: shipment.status, newStatus: next });
+        shipment.status = next;
+        shipmentsUpdated = 1;
+      }
+    }
+    await em.flush();
+    if (isNew) {
+      await this.deps.eventBus.emit("shipment_tracking.shipment.created", {
+        id: shipment.id,
+        awbNumber: shipment.awbNumber,
+        trackingJobId: job.id,
+        tenantId: job.tenantId,
+        organizationId: job.organizationId
+      });
+    }
+    await this.emitShipmentDerivedChanges([shipment], statusChanges, etaChanges, etdChanges);
+    const latestEventAt = allEvents.length > 0 ? allEvents[allEvents.length - 1].eventDateTime : null;
+    const staleArrived = shipment.status === "ARRIVED" && latestEventAt != null && latestEventAt < staleArrivalCutoff();
+    return {
+      shipmentsCreated,
+      shipmentsUpdated,
+      allComplete: shipment.status === "DELIVERED" || staleArrived
+    };
+  }
+  async syncShipmentsFromEvents(em, job, carrierResult, bicConfig) {
+    if (job.mode === "air") {
+      return this.syncAirShipmentFromEvents(em, job, carrierResult, bicConfig);
+    }
+    const allEvents = await em.find(
+      TrackingEvent,
+      { trackingJob: job },
+      { orderBy: { eventDateTime: "asc" } }
+    );
+    if (allEvents.length === 0) {
+      return { shipmentsCreated: 0, shipmentsUpdated: 0, allComplete: false };
+    }
+    const containerNumbers = /* @__PURE__ */ new Set();
+    for (const event of allEvents) {
+      if (event.eventType === "EQUIPMENT" && event.equipmentReference) {
+        containerNumbers.add(event.equipmentReference);
+      }
+    }
+    if (containerNumbers.size === 0 && job.referenceType === "container") {
+      containerNumbers.add(job.referenceValue);
+    }
+    if (containerNumbers.size === 0) {
+      return { shipmentsCreated: 0, shipmentsUpdated: 0, allComplete: false };
+    }
+    const existingShipments = await em.find(Shipment, {
+      trackingJob: job,
+      deletedAt: null
+    });
+    const shipmentsByContainer = new Map(
+      existingShipments.map((s) => [s.containerNumber, s])
+    );
+    let shipmentsCreated = 0;
+    let shipmentsUpdated = 0;
+    const newShipments = [];
+    const statusChanges = [];
+    const etaChanges = [];
+    const etdChanges = [];
+    for (const containerNumber of containerNumbers) {
+      let shipment = shipmentsByContainer.get(containerNumber);
+      if (!shipment) {
+        shipment = em.create(Shipment, {
+          organizationId: job.organizationId,
+          tenantId: job.tenantId,
+          trackingJob: job,
+          carrierCode: job.carrierCode,
+          containerNumber,
+          bookingNumber: job.referenceType === "booking" ? job.referenceValue : carrierResult.bookingNumber,
+          bolNumber: job.referenceType === "bol" ? job.referenceValue : carrierResult.bolNumber,
+          // Initialize with basic location from job's UN/LOCODE if available
+          // Will be enriched with full facility data from events later
+          originLocation: job.originUnlocode ? createBasicLocation(job.originUnlocode) : null,
+          destinationLocation: job.destinationUnlocode ? createBasicLocation(job.destinationUnlocode) : null,
+          status: "PENDING"
+        });
+        em.persist(shipment);
+        shipmentsByContainer.set(containerNumber, shipment);
+        shipmentsCreated++;
+        newShipments.push({ shipment, containerNumber });
+        trackingLogger.info("Auto-created Shipment", {
+          shipmentId: shipment.id,
+          containerNumber,
+          trackingJobId: job.id,
+          carrierCode: job.carrierCode
+        });
+      }
+      if (!shipment.bookingNumber && carrierResult.bookingNumber) {
+        shipment.bookingNumber = carrierResult.bookingNumber;
+      }
+      if (!shipment.bolNumber && carrierResult.bolNumber) {
+        shipment.bolNumber = carrierResult.bolNumber;
+      }
+      if (carrierResult.extra) {
+        shipment.extra = { ...shipment.extra ?? {}, ...carrierResult.extra };
+      }
+      const result = await this.deriveShipmentStateFromEvents(em, shipment, allEvents, bicConfig);
+      if (result.changed) {
+        shipmentsUpdated++;
+        if (result.statusChange) {
+          statusChanges.push({
+            shipment,
+            previousStatus: result.statusChange.previousStatus,
+            newStatus: result.statusChange.newStatus
+          });
+        }
+        if (result.etaChange) {
+          etaChanges.push({
+            shipment,
+            previousEta: result.etaChange.previousEta,
+            newEta: result.etaChange.newEta
+          });
+        }
+        if (result.etdChange) {
+          etdChanges.push({
+            shipment,
+            previousEtd: result.etdChange.previousEtd,
+            newEtd: result.etdChange.newEtd
+          });
+        }
+      }
+    }
+    await em.flush();
+    for (const { shipment, containerNumber } of newShipments) {
+      await this.deps.eventBus.emit("shipment_tracking.shipment.created", {
+        id: shipment.id,
+        containerNumber,
+        trackingJobId: job.id,
+        tenantId: job.tenantId,
+        organizationId: job.organizationId
+      });
+    }
+    const polledShipments = [...containerNumbers].map((cn) => shipmentsByContainer.get(cn)).filter((s) => s != null);
+    await this.emitShipmentDerivedChanges(polledShipments, statusChanges, etaChanges, etdChanges);
+    const allComplete = allContainersComplete(allEvents, containerNumbers) || destinationArrivedBefore(allEvents, job.destinationUnlocode, staleArrivalCutoff());
+    return { shipmentsCreated, shipmentsUpdated, allComplete };
+  }
+  /**
+   * Emit the shipment status/lifecycle/timestamp change events produced by a round of
+   * deriveShipmentStateFromEvents. Shared by the carrier poll (syncShipmentsFromEvents)
+   * and the real-time AIS refresh (refreshShipmentsFromEvents) so both paths surface the
+   * same downstream events. Call AFTER flushing so subscribers can fetch committed rows.
+   *
+   * @param updatedShipments - shipments to emit a bare `shipment.updated` for when they
+   *   did not also produce a status change (status changes already emit `updated`).
+   */
+  async emitShipmentDerivedChanges(updatedShipments, statusChanges, etaChanges, etdChanges) {
+    for (const { shipment, previousStatus, newStatus } of statusChanges) {
+      await this.deps.eventBus.emit("shipment_tracking.shipment.status_changed", {
+        id: shipment.id,
+        previousStatus,
+        newStatus,
+        tenantId: shipment.tenantId,
+        organizationId: shipment.organizationId
+      });
+      if (newStatus === "BOOKED" && previousStatus === "PENDING") {
+        await this.deps.eventBus.emit("shipment_tracking.shipment.booked", {
+          id: shipment.id,
+          tenantId: shipment.tenantId,
+          organizationId: shipment.organizationId
+        });
+      }
+      if (newStatus === "PRE_ARRIVAL") {
+        await this.deps.eventBus.emit("shipment_tracking.shipment.pre_arrival", {
+          id: shipment.id,
+          tenantId: shipment.tenantId,
+          organizationId: shipment.organizationId
+        });
+      }
+      if (newStatus === "DELIVERED") {
+        await this.deps.eventBus.emit("shipment_tracking.shipment.delivered", {
+          id: shipment.id,
+          tenantId: shipment.tenantId,
+          organizationId: shipment.organizationId
+        });
+      }
+      await this.deps.eventBus.emit("shipment_tracking.shipment.updated", {
+        id: shipment.id,
+        tenantId: shipment.tenantId,
+        organizationId: shipment.organizationId
+      });
+    }
+    const alreadyEmittedIds = new Set(statusChanges.map((sc) => sc.shipment.id));
+    for (const shipment of updatedShipments) {
+      if (!alreadyEmittedIds.has(shipment.id)) {
+        await this.deps.eventBus.emit("shipment_tracking.shipment.updated", {
+          id: shipment.id,
+          tenantId: shipment.tenantId,
+          organizationId: shipment.organizationId
+        });
+      }
+    }
+    for (const { shipment, previousEta, newEta } of etaChanges) {
+      await this.deps.eventBus.emit("shipment_tracking.transport.eta_updated", {
+        id: shipment.id,
+        previousEta: previousEta.toISOString(),
+        newEta: newEta.toISOString(),
+        tenantId: shipment.tenantId,
+        organizationId: shipment.organizationId
+      });
+    }
+    for (const { shipment, previousEtd, newEtd } of etdChanges) {
+      await this.deps.eventBus.emit("shipment_tracking.transport.etd_updated", {
+        id: shipment.id,
+        previousEtd: previousEtd.toISOString(),
+        newEtd: newEtd.toISOString(),
+        tenantId: shipment.tenantId,
+        organizationId: shipment.organizationId
+      });
+    }
+  }
+  /**
+   * Re-derive denormalized state (cargoEvents, routeStops, status, ETA/ETD/ATA/ATD, seals,
+   * locations) for a tracking job's shipments from their persisted TrackingEvents, then emit
+   * the resulting change events. Used by real-time ingestion (e.g. AIS POI events over NATS)
+   * so the Journey Timeline and derived state update immediately instead of waiting for the
+   * next carrier poll. Idempotent: deriveShipmentStateFromEvents is a no-op when nothing changed.
+   *
+   * @param em - entity manager managing the (already flushed) new TrackingEvents
+   * @param trackingJobId - the job whose shipments to refresh
+   * @param shipmentIds - optional subset; defaults to all of the job's shipments
+   */
+  async refreshShipmentsFromEvents(em, trackingJobId, shipmentIds) {
+    const job = await em.findOne(TrackingJob, { id: trackingJobId });
+    if (!job) return;
+    if (job.mode === "air") return;
+    const shipments = shipmentIds && shipmentIds.length > 0 ? await em.find(Shipment, { trackingJob: job, deletedAt: null, id: { $in: shipmentIds } }) : await em.find(Shipment, { trackingJob: job, deletedAt: null });
+    if (shipments.length === 0) return;
+    const allEvents = await em.find(
+      TrackingEvent,
+      { trackingJob: job },
+      { orderBy: { eventDateTime: "asc" } }
+    );
+    if (allEvents.length === 0) return;
+    const bicConfig = await this.loadBicConfig(em, {
+      organizationId: job.organizationId,
+      tenantId: job.tenantId
+    });
+    const statusChanges = [];
+    const etaChanges = [];
+    const etdChanges = [];
+    const changedShipments = [];
+    for (const shipment of shipments) {
+      const result = await this.deriveShipmentStateFromEvents(em, shipment, allEvents, bicConfig);
+      if (!result.changed) continue;
+      changedShipments.push(shipment);
+      if (result.statusChange) statusChanges.push({ shipment, ...result.statusChange });
+      if (result.etaChange) etaChanges.push({ shipment, ...result.etaChange });
+      if (result.etdChange) etdChanges.push({ shipment, ...result.etdChange });
+    }
+    if (changedShipments.length === 0) return;
+    await em.flush();
+    await this.emitShipmentDerivedChanges(changedShipments, statusChanges, etaChanges, etdChanges);
+  }
+  /**
+   * Derives and updates Shipment state from TrackingEvents.
+   * Filters events by equipmentReference to get container-specific events.
+   * TRANSPORT events (no equipmentReference) apply to all containers.
+   * 
+   * Returns status change info and time changes so caller can emit events after flush.
+   */
+  async deriveShipmentStateFromEvents(em, shipment, allEvents, bicConfig, airStatus) {
+    const containerEvents = allEvents.filter((event) => {
+      if (event.eventType === "TRANSPORT") return true;
+      if (event.eventType === "EQUIPMENT") {
+        return event.equipmentReference === shipment.containerNumber;
+      }
+      return false;
+    });
+    if (containerEvents.length === 0) {
+      return { changed: false };
+    }
+    const originUnlocode = shipment.originLocation?.unlocode ?? null;
+    const destinationUnlocode = shipment.destinationLocation?.unlocode ?? null;
+    const context = {
+      originUnlocode,
+      destinationUnlocode
+    };
+    const times = extractShipmentTimes(
+      containerEvents.map((event) => ({
+        eventCode: event.eventCode,
+        eventClassifierCode: event.eventClassifierCode,
+        eventDateTime: event.eventDateTime,
+        eventDateTimeOffset: event.eventDateTimeOffset,
+        eventCreatedDateTime: event.eventCreatedDateTime,
+        locationUnlocode: event.locationUnlocode
+      })),
+      context
+    );
+    const latestEvent = containerEvents[containerEvents.length - 1];
+    const latestVesselInfo = findLatestVesselInfo(containerEvents);
+    const previousEta = getPrimaryTimestampValue(shipment.etaTimestamps);
+    const previousEtd = getPrimaryTimestampValue(shipment.etdTimestamps);
+    const previousAtd = getPrimaryTimestampValue(shipment.atdTimestamps);
+    const previousAta = getPrimaryTimestampValue(shipment.ataTimestamps);
+    const mergedTimestamps = mergeExtractedTimestamps(
+      {
+        etdTimestamps: shipment.etdTimestamps,
+        etaTimestamps: shipment.etaTimestamps,
+        atdTimestamps: shipment.atdTimestamps,
+        ataTimestamps: shipment.ataTimestamps
+      },
+      times,
+      "carrier_api",
+      latestEvent?.sourceEventId
+    );
+    const newEta = getPrimaryTimestampValue(mergedTimestamps.etaTimestamps);
+    const newEtd = getPrimaryTimestampValue(mergedTimestamps.etdTimestamps);
+    const newAtd = getPrimaryTimestampValue(mergedTimestamps.atdTimestamps);
+    const newAta = getPrimaryTimestampValue(mergedTimestamps.ataTimestamps);
+    const previousStatus = shipment.status;
+    const newStatus = airStatus !== void 0 ? deriveAirShipmentStatus(airStatus, shipment.status) : deriveShipmentStatus(
+      containerEvents.map((event) => ({
+        eventCode: event.eventCode,
+        eventClassifierCode: event.eventClassifierCode,
+        locationUnlocode: event.locationUnlocode
+      })),
+      context,
+      shipment.status,
+      { eta: newEta, ata: newAta }
+    );
+    const etaChanged = newEta && previousEta && newEta.getTime() !== previousEta.getTime();
+    const etdChanged = newEtd && previousEtd && newEtd.getTime() !== previousEtd.getTime();
+    const changed = previousStatus !== newStatus || mergedTimestamps.changed || newEtd && !previousEtd || etdChanged || newEta && !previousEta || etaChanged || newAtd && !previousAtd || newAtd && previousAtd && newAtd.getTime() !== previousAtd.getTime() || newAta && !previousAta || newAta && previousAta && newAta.getTime() !== previousAta.getTime() || shipment.vesselName !== latestEvent?.vesselName || containerEvents.length !== shipment.eventCount;
+    if (!changed) {
+      return { changed: false };
+    }
+    shipment.status = newStatus;
+    shipment.etdTimestamps = mergedTimestamps.etdTimestamps;
+    shipment.etaTimestamps = mergedTimestamps.etaTimestamps;
+    shipment.atdTimestamps = mergedTimestamps.atdTimestamps;
+    shipment.ataTimestamps = mergedTimestamps.ataTimestamps;
+    if (latestVesselInfo) {
+      shipment.vesselName = latestVesselInfo.vesselName ?? shipment.vesselName;
+      shipment.vesselImo = latestVesselInfo.vesselImo ?? shipment.vesselImo;
+      shipment.voyageNumber = latestVesselInfo.voyageNumber ?? shipment.voyageNumber;
+    }
+    if (!shipment.isoEquipmentCode) {
+      const eventWithIsoCode = containerEvents.find((e) => e.isoEquipmentCode);
+      if (eventWithIsoCode) {
+        shipment.isoEquipmentCode = eventWithIsoCode.isoEquipmentCode;
+      }
+    }
+    if (!shipment.bookingNumber) {
+      for (const event of containerEvents) {
+        const bkgRef = event.relatedDocumentReferences?.find((ref) => ref.type === "BKG");
+        if (bkgRef?.value) {
+          shipment.bookingNumber = bkgRef.value;
+          break;
+        }
+      }
+    }
+    if (!shipment.bolNumber) {
+      for (const event of containerEvents) {
+        const bolRef = event.relatedDocumentReferences?.find((ref) => ref.type === "TRD" || ref.type === "SHI");
+        if (bolRef?.value) {
+          shipment.bolNumber = bolRef.value;
+          break;
+        }
+      }
+    }
+    if (latestEvent) {
+      shipment.lastEventAt = latestEvent.eventDateTime;
+    }
+    shipment.eventCount = containerEvents.length;
+    const cargoEvents = containerEvents.map(mapTrackingEventToEntry);
+    shipment.cargoEvents = cargoEvents;
+    shipment.routeStops = extractRouteFromEvents(cargoEvents, {
+      originUnlocode,
+      destinationUnlocode
+    });
+    const allSeals = containerEvents.flatMap((e) => e.seals ?? []).filter((seal) => seal.number);
+    if (allSeals.length > 0) {
+      const seenSeals = /* @__PURE__ */ new Map();
+      for (const seal of allSeals) {
+        seenSeals.set(seal.number, seal);
+      }
+      shipment.seals = Array.from(seenSeals.values());
+    } else {
+      shipment.seals = null;
+    }
+    const originEventsAtLocation = containerEvents.filter(
+      (e) => e.locationUnlocode === originUnlocode
+    );
+    const originEvent = (
+      // Priority 1: LOAD event at origin
+      originEventsAtLocation.find((e) => e.eventCode === "LOAD" && e.eventClassifierCode === "ACT") ?? // Priority 2: Any event with facility code at origin
+      originEventsAtLocation.find((e) => e.facilityCode != null) ?? // Fallback: First event at origin, or LOAD event anywhere if no origin specified
+      originEventsAtLocation[0] ?? (!originUnlocode ? containerEvents.find((e) => e.eventCode === "LOAD" && e.eventClassifierCode === "ACT") : null)
+    );
+    const destEventsAtLocation = containerEvents.filter(
+      (e) => e.locationUnlocode === destinationUnlocode
+    );
+    const destEventsReversed = [...destEventsAtLocation].reverse();
+    const destEvent = (
+      // Priority 1: DISC event at destination (last one)
+      destEventsReversed.find((e) => e.eventCode === "DISC" && e.eventClassifierCode === "ACT") ?? // Priority 2: Any event with facility code at destination (last one)
+      destEventsReversed.find((e) => e.facilityCode != null) ?? // Fallback: Last event at destination, or DISC/ARRI event anywhere if no destination specified
+      destEventsReversed[0] ?? (!destinationUnlocode ? [...containerEvents].reverse().find((e) => (e.eventCode === "DISC" || e.eventCode === "ARRI") && e.eventClassifierCode === "ACT") : null)
+    );
+    if (originEvent) {
+      shipment.originLocation = buildLocationFromEvent({
+        locationName: originEvent.locationName,
+        locationUnlocode: originEvent.locationUnlocode,
+        locationCountry: originEvent.locationCountry,
+        facilityCode: originEvent.facilityCode,
+        facilityCodeListProvider: originEvent.facilityCodeListProvider,
+        facilityTypeCode: originEvent.facilityTypeCode,
+        facilityAddress: originEvent.facilityAddress,
+        latitude: originEvent.latitude,
+        longitude: originEvent.longitude
+      });
+    }
+    if (destEvent) {
+      shipment.destinationLocation = buildLocationFromEvent({
+        locationName: destEvent.locationName,
+        locationUnlocode: destEvent.locationUnlocode,
+        locationCountry: destEvent.locationCountry,
+        facilityCode: destEvent.facilityCode,
+        facilityCodeListProvider: destEvent.facilityCodeListProvider,
+        facilityTypeCode: destEvent.facilityTypeCode,
+        facilityAddress: destEvent.facilityAddress,
+        latitude: destEvent.latitude,
+        longitude: destEvent.longitude
+      });
+    }
+    if (bicConfig) {
+      await this.enrichShipmentLocationsWithBic(shipment, containerEvents, bicConfig);
+    }
+    const scope = { organizationId: shipment.organizationId, tenantId: shipment.tenantId };
+    const carrierCode = shipment.carrierCode?.toUpperCase() ?? null;
+    shipment.originLocation = await applyLocationOverrideIfExists(
+      em,
+      shipment.originLocation,
+      carrierCode,
+      scope
+    );
+    shipment.destinationLocation = await applyLocationOverrideIfExists(
+      em,
+      shipment.destinationLocation,
+      carrierCode,
+      scope
+    );
+    if (shipment.routeStops) {
+      for (const stop of shipment.routeStops) {
+        if (stop.facilityCode && stop.facilityCodeListProvider) {
+          const overridden = await applyLocationOverrideIfExists(em, {
+            name: stop.location,
+            unlocode: stop.unlocode ?? null,
+            countryCode: stop.unlocode?.slice(0, 2) ?? null,
+            facilityCode: stop.facilityCode,
+            facilityCodeListProvider: stop.facilityCodeListProvider,
+            facilityTypeCode: stop.facilityTypeCode ?? null,
+            address: stop.facilityAddress ?? null,
+            coords: stop.coords ?? null,
+            operatorName: null,
+            source: "dcsa"
+          }, carrierCode, scope);
+          if (overridden && overridden.source === "manual") {
+            stop.location = overridden.name;
+            stop.facilityAddress = overridden.address;
+            stop.coords = overridden.coords;
+          }
+        }
+      }
+    }
+    const statusChange = previousStatus !== newStatus ? { previousStatus, newStatus } : void 0;
+    const etaChange = etaChanged && previousEta && newEta ? { previousEta, newEta } : void 0;
+    const etdChange = etdChanged && previousEtd && newEtd ? { previousEtd, newEtd } : void 0;
+    return { changed: true, statusChange, etaChange, etdChange };
+  }
+  /**
+   * Emits events for a newly created TrackingEvent.
+   */
+  async emitTrackingEventCreated(event, job) {
+    const eventPayload = {
+      id: event.id,
+      trackingJobId: job.id,
+      tenantId: event.tenantId,
+      organizationId: event.organizationId,
+      // Source
+      source: event.source,
+      sourceEventId: event.sourceEventId,
+      // Core event fields
+      eventType: event.eventType,
+      eventCode: event.eventCode,
+      eventClassifierCode: event.eventClassifierCode,
+      eventDateTime: event.eventDateTime?.toISOString(),
+      description: event.description,
+      // Equipment fields
+      equipmentReference: event.equipmentReference,
+      isoEquipmentCode: event.isoEquipmentCode,
+      emptyIndicatorCode: event.emptyIndicatorCode,
+      isTransshipmentMove: event.isTransshipmentMove,
+      // Location fields
+      locationName: event.locationName,
+      locationUnlocode: event.locationUnlocode,
+      locationCountry: event.locationCountry,
+      facilityCode: event.facilityCode,
+      facilityTypeCode: event.facilityTypeCode,
+      // Transport call fields
+      vesselName: event.vesselName,
+      vesselImo: event.vesselImo,
+      voyageNumber: event.voyageNumber,
+      carrierServiceCode: event.carrierServiceCode,
+      modeOfTransport: event.modeOfTransport,
+      // Document references
+      relatedDocumentReferences: event.relatedDocumentReferences,
+      // Metadata
+      publisherName: event.publisherName,
+      publisherRole: event.publisherRole
+    };
+    await this.deps.eventBus.emit("shipment_tracking.tracking_event.created", eventPayload);
+    if (isSignificantMilestone({
+      eventType: event.eventType,
+      eventCode: event.eventCode,
+      eventClassifierCode: event.eventClassifierCode
+    })) {
+      const dcsaEventType = mapDcsaEventToWebhookType({
+        eventType: event.eventType,
+        eventCode: event.eventCode,
+        eventClassifierCode: event.eventClassifierCode
+      });
+      await this.deps.eventBus.emit(dcsaEventType, eventPayload);
+    }
+  }
+  /**
+   * Loads BIC Facility API configuration for a tenant/organization.
+   */
+  async loadBicConfig(em, scope) {
+    return findOneWithDecryption(
+      em,
+      BicConfig,
+      {
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        isEnabled: true
+      },
+      void 0,
+      scope
+    );
+  }
+  /**
+   * Enriches shipment origin/destination locations and route stops with BIC Facility API data.
+   * Only fetches data for facilities that are incomplete (missing coords or address).
+   * One API call per unique facility code per poll.
+   */
+  async enrichShipmentLocationsWithBic(shipment, events, bicConfig) {
+    const facilitiesToEnrich = /* @__PURE__ */ new Map();
+    if (shipment.originLocation && !isLocationComplete(shipment.originLocation) && shipment.originLocation.facilityCode) {
+      const provider = shipment.originLocation.facilityCodeListProvider ?? "SMDG";
+      facilitiesToEnrich.set(shipment.originLocation.facilityCode, {
+        code: shipment.originLocation.facilityCode,
+        provider,
+        unlocode: shipment.originLocation.unlocode ?? ""
+      });
+    }
+    if (shipment.destinationLocation && !isLocationComplete(shipment.destinationLocation) && shipment.destinationLocation.facilityCode) {
+      const provider = shipment.destinationLocation.facilityCodeListProvider ?? "SMDG";
+      facilitiesToEnrich.set(shipment.destinationLocation.facilityCode, {
+        code: shipment.destinationLocation.facilityCode,
+        provider,
+        unlocode: shipment.destinationLocation.unlocode ?? ""
+      });
+    }
+    for (const event of events) {
+      if (event.facilityCode && event.latitude == null && !event.facilityAddress) {
+        const provider = event.facilityCodeListProvider ?? "SMDG";
+        if (!facilitiesToEnrich.has(event.facilityCode)) {
+          facilitiesToEnrich.set(event.facilityCode, {
+            code: event.facilityCode,
+            provider,
+            unlocode: event.locationUnlocode ?? ""
+          });
+        }
+      }
+    }
+    if (facilitiesToEnrich.size === 0) {
+      return;
+    }
+    const client = new BicApiClient({
+      baseUrl: bicConfig.baseUrl,
+      username: bicConfig.username,
+      password: bicConfig.password
+    });
+    const facilityMap = /* @__PURE__ */ new Map();
+    for (const [code, info] of facilitiesToEnrich) {
+      try {
+        const facility = await client.getFacility(info.code, info.provider, info.unlocode);
+        if (facility) {
+          facilityMap.set(code, facility);
+        }
+      } catch (error) {
+        trackingLogger.error("Failed to fetch BIC facility", {
+          facilityCode: code,
+          codeProvider: info.provider,
+          unlocode: info.unlocode,
+          shipmentId: shipment.id,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    if (facilityMap.size === 0) {
+      return;
+    }
+    if (shipment.originLocation?.facilityCode && facilityMap.has(shipment.originLocation.facilityCode)) {
+      const bic = facilityMap.get(shipment.originLocation.facilityCode);
+      shipment.originLocation = this.mergeLocationWithBicFacility(shipment.originLocation, bic);
+    }
+    if (shipment.destinationLocation?.facilityCode && facilityMap.has(shipment.destinationLocation.facilityCode)) {
+      const bic = facilityMap.get(shipment.destinationLocation.facilityCode);
+      shipment.destinationLocation = this.mergeLocationWithBicFacility(shipment.destinationLocation, bic);
+    }
+    if (shipment.routeStops) {
+      for (const stop of shipment.routeStops) {
+        if (stop.facilityCode && facilityMap.has(stop.facilityCode)) {
+          const bic = facilityMap.get(stop.facilityCode);
+          const coords = BicApiClient.parseCoordinates(bic);
+          const address = BicApiClient.formatAddress(bic);
+          if (!stop.coords && coords) {
+            stop.coords = coords;
+          }
+          if (!stop.facilityAddress && address) {
+            stop.facilityAddress = address;
+          }
+        }
+      }
+    }
+    if (shipment.cargoEvents) {
+      for (const event of shipment.cargoEvents) {
+        if (event.facilityCode && facilityMap.has(event.facilityCode)) {
+          const bic = facilityMap.get(event.facilityCode);
+          const coords = BicApiClient.parseCoordinates(bic);
+          const address = BicApiClient.formatAddress(bic);
+          if (event.latitude == null && coords) {
+            event.latitude = coords.latitude;
+            event.longitude = coords.longitude;
+          }
+          if (!event.facilityAddress && address) {
+            event.facilityAddress = address;
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Merges BIC facility data into a FacilityLocation (only fills missing fields).
+   */
+  mergeLocationWithBicFacility(location, bic) {
+    const coords = BicApiClient.parseCoordinates(bic);
+    const address = BicApiClient.formatAddress(bic);
+    const operatorName = BicApiClient.getOperatorName(bic);
+    const facilityName = BicApiClient.getFacilityName(bic);
+    return mergeLocationWithBicData(location, {
+      name: facilityName ?? void 0,
+      address: address ?? void 0,
+      coords: coords ?? void 0,
+      operatorName: operatorName ?? void 0
+    });
+  }
+  /**
+   * Stops an active tracking job (sets status to 'deactivated').
+   * Tenant-scoped: refuses to stop a job not belonging to the caller's tenant.
+   * Idempotent: returns { stopped: false } when the job is already inactive,
+   * doesn't exist, or belongs to a different tenant.
+   */
+  async stopTrackingJob(jobId, ctx) {
+    const em = this.deps.em();
+    const job = await em.findOne(TrackingJob, {
+      id: jobId,
+      organizationId: ctx.organizationId,
+      tenantId: ctx.tenantId,
+      deletedAt: null
+    });
+    if (!job) {
+      return { stopped: false };
+    }
+    if (job.status !== "active" && job.status !== "paused") {
+      return { stopped: false };
+    }
+    await this.stopJobInline(em, job);
+    trackingLogger.info("Tracking job stopped", {
+      trackingJobId: jobId,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId
+    });
+    return { stopped: true };
+  }
+  /**
+   * Stop a job (target status defaults to `deactivated`) and emit
+   * `tracking_job.completed`, operating on the given EntityManager (the job must
+   * be managed by it). Shared by the public `stopTrackingJob` (externally
+   * stopped → `deactivated`) and the carrier-poll auto-stop (cargo finished →
+   * `completed`) so both routes flush + emit identically. Either status is
+   * excluded from the `status: 'active'` poll filter, so polling stops.
+   */
+  async stopJobInline(em, job, status = "deactivated") {
+    job.status = status;
+    job.nextPollAt = null;
+    await em.flush();
+    await this.deps.eventBus.emit("shipment_tracking.tracking_job.completed", {
+      id: job.id,
+      tenantId: job.tenantId,
+      organizationId: job.organizationId
+    });
+  }
+  /**
+   * Reconciliation: stops any active TrackingJob that has no folder_legs row
+   * referencing it via tracking_job_id. Used by the daily reconciliation cron
+   * to clean up orphans created by failed Phase B/C re-tracking flows.
+   *
+   * Returns { stoppedCount } so the cron can surface to ops.
+   * The optional folderLegsTracker param exists so this code can run from
+   * @freighttech/shipment-tracking without a hard import on @freighttech/projects:
+   * the caller passes a function that returns the set of tracking_job_ids
+   * currently referenced by folder_legs.
+   */
+  async reconcileOrphanedTrackingJobs(folderLegTrackingJobIds, ctx) {
+    const em = this.deps.em();
+    const filter = {
+      status: "active",
+      deletedAt: null
+    };
+    if (ctx?.organizationId) filter.organizationId = ctx.organizationId;
+    if (ctx?.tenantId) filter.tenantId = ctx.tenantId;
+    const activeJobs = await em.find(TrackingJob, filter);
+    let stoppedCount = 0;
+    for (const job of activeJobs) {
+      if (folderLegTrackingJobIds.has(job.id)) continue;
+      const result = await this.stopTrackingJob(job.id, {
+        organizationId: job.organizationId,
+        tenantId: job.tenantId
+      });
+      if (result.stopped) stoppedCount++;
+    }
+    return { stoppedCount, checked: activeJobs.length };
+  }
+  /**
+   * Records an error on a tracking job.
+   */
+  /**
+   * Backs a job off by `backoffMs` and logs `message` in its error history,
+   * WITHOUT touching retryCount. For account-level/transient ShipsGo conditions
+   * (402 credits, 429 rate limit, 403 auth) that must not consume the per-job
+   * failure budget (which would flip the job to 'failed') nor keep re-hitting an
+   * exhausted/throttled account every poll. The job resumes on its own.
+   */
+  async recordTransientBackoff(em, job, message, backoffMs) {
+    const history = job.errorHistory ?? [];
+    history.push({ date: (/* @__PURE__ */ new Date()).toISOString(), message });
+    if (history.length > 20) history.splice(0, history.length - 20);
+    job.errorHistory = history;
+    job.lastPollAt = /* @__PURE__ */ new Date();
+    job.nextPollAt = new Date(Date.now() + backoffMs);
+    await em.flush();
+  }
+  /** ShipsGo credit-exhaustion (HTTP 402): back off ~6h until credits are topped up. */
+  async recordCreditExhaustion(em, job) {
+    await this.recordTransientBackoff(em, job, "ShipsGo credits exhausted (HTTP 402)", 6 * 60 * 60 * 1e3);
+  }
+  async recordJobError(em, job, message) {
+    const history = job.errorHistory ?? [];
+    history.push({ date: (/* @__PURE__ */ new Date()).toISOString(), message });
+    if (history.length > 20) {
+      history.splice(0, history.length - 20);
+    }
+    job.errorHistory = history;
+    job.retryCount = (job.retryCount || 0) + 1;
+    job.lastPollAt = /* @__PURE__ */ new Date();
+    if (job.retryCount >= 10) {
+      job.status = "failed";
+      await em.flush();
+      await this.deps.eventBus.emit("shipment_tracking.tracking_job.failed", {
+        id: job.id,
+        carrierCode: job.carrierCode,
+        retryCount: job.retryCount,
+        lastError: message,
+        tenantId: job.tenantId,
+        organizationId: job.organizationId
+      });
+      return;
+    }
+    await em.flush();
+  }
+}
+export {
+  TrackingService
+};
+//# sourceMappingURL=trackingService.js.map