@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/subscribers/dcsa-event-webhook-dispatch.ts

@@ -0,0 +1,115 @@
+import type { DocumentReference } from '../data/entities'
+
+/**
+ * Handles DCSA-compliant transport and equipment events and dispatches webhooks.
+ * These are granular events like transport.departed, equipment.loaded, etc.
+ */
+export const metadata = {
+  event: 'shipment_tracking.transport.*,shipment_tracking.equipment.*',
+  persistent: true,
+  id: 'shipment_tracking:dcsa-event-webhook-dispatch',
+}
+
+type DcsaEventPayload = {
+  id: string
+  shipmentId: string
+  tenantId: string
+  organizationId: string
+
+  // Core event fields
+  eventId: string
+  eventType: string
+  eventCode: string
+  eventClassifierCode?: string | null
+  eventDateTime?: string | null
+  description?: string | null
+
+  // Equipment fields
+  equipmentReference?: string | null
+  isoEquipmentCode?: string | null
+  emptyIndicatorCode?: string | null
+  isTransshipmentMove?: boolean | null
+
+  // Location fields
+  locationName?: string | null
+  locationUnlocode?: string | null
+  locationCountry?: string | null
+  facilityCode?: string | null
+  facilityTypeCode?: string | null
+
+  // Transport call fields
+  vesselName?: string | null
+  vesselImo?: string | null
+  voyageNumber?: string | null
+  carrierServiceCode?: string | null
+  modeOfTransport?: string | null
+
+  // Document references
+  relatedDocumentReferences?: DocumentReference[] | null
+
+  // Metadata
+  publisherName?: string | null
+  publisherRole?: string | null
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+  eventName: string
+}
+
+export default async function handle(payload: DcsaEventPayload, ctx: ResolverContext) {
+  try {
+    const webhookService = ctx.resolve<any>('shipmentTrackingWebhookService')
+
+    await webhookService.dispatchEvent({
+      eventType: ctx.eventName,
+      payload: {
+        event: {
+          // IDs
+          id: payload.id,
+          shipmentId: payload.shipmentId,
+
+          // Core event fields
+          eventType: payload.eventType,
+          eventCode: payload.eventCode,
+          eventClassifierCode: payload.eventClassifierCode,
+          eventDateTime: payload.eventDateTime,
+          description: payload.description,
+
+          // Equipment fields (critical for multi-container bookings)
+          equipmentReference: payload.equipmentReference,
+          isoEquipmentCode: payload.isoEquipmentCode,
+          emptyIndicatorCode: payload.emptyIndicatorCode,
+          isTransshipmentMove: payload.isTransshipmentMove,
+
+          // Location fields
+          locationName: payload.locationName,
+          locationUnlocode: payload.locationUnlocode,
+          locationCountry: payload.locationCountry,
+          facilityCode: payload.facilityCode,
+          facilityTypeCode: payload.facilityTypeCode,
+
+          // Transport call fields
+          vesselName: payload.vesselName,
+          vesselImo: payload.vesselImo,
+          voyageNumber: payload.voyageNumber,
+          carrierServiceCode: payload.carrierServiceCode,
+          modeOfTransport: payload.modeOfTransport,
+
+          // Document references
+          relatedDocumentReferences: payload.relatedDocumentReferences,
+
+          // Metadata
+          publisherName: payload.publisherName,
+          publisherRole: payload.publisherRole,
+        },
+      },
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId,
+    })
+
+    console.debug(`[shipment-tracking:dcsa-webhook] Dispatched ${ctx.eventName} for tracking event ${payload.id}`)
+  } catch (error) {
+    console.error(`[shipment-tracking:dcsa-webhook] Failed to dispatch ${ctx.eventName} webhook:`, error)
+  }
+}

package/src/modules/shipment_tracking/subscribers/poi-event-notification.ts

@@ -0,0 +1,144 @@
+/**
+ * POI Event Notification Subscriber
+ *
+ * Subscribes to per-tracking-job POI proximity events and creates in-app
+ * notifications for the user who created the tracking job.
+ *
+ * These events are emitted once per tracking job (BOL/Booking), not per
+ * shipment (container), so no deduplication is needed.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { resolveNotificationService } from '@open-mercato/core/modules/notifications/lib/notificationService'
+import { buildNotificationFromType } from '@open-mercato/core/modules/notifications/lib/notificationBuilder'
+import type { ProximityEventType } from '../lib/poi-types'
+import { getTrackingJobCreator } from '../lib/audit-helpers'
+import { notificationTypes } from '../notifications'
+
+export const metadata = {
+  event: 'shipment_tracking.tracking_job.poi.*',
+  persistent: true,
+  id: 'shipment_tracking:tracking-job-poi-notification',
+}
+
+type TrackingJobPoiEventPayload = {
+  trackingJobId: string
+  shipmentId: string
+  trackingEventId: string
+  organizationId: string
+  tenantId: string
+  vesselName: string
+  vesselMmsi: number
+  vesselImo: string | null
+  eventType: ProximityEventType
+  poiCode: string | null
+  latitude: number
+  longitude: number
+  eventDateTime: string
+  distanceToPoiMeters: number | null
+  containerNumber?: string | null
+  bookingNumber?: string | null
+  bolNumber?: string | null
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+/**
+ * Map POI event types to per-job notification type identifiers.
+ */
+function mapEventTypeToNotificationType(eventType: ProximityEventType): string {
+  const map: Record<ProximityEventType, string> = {
+    PORT_ARRIVAL: 'shipment_tracking.tracking_job.poi.port_arrival',
+    PORT_PROXIMITY_ARRIVAL: 'shipment_tracking.tracking_job.poi.port_proximity_arrival',
+    PORT_PROXIMITY_DEPARTURE: 'shipment_tracking.tracking_job.poi.port_departure',
+    TERMINAL_ARRIVAL: 'shipment_tracking.tracking_job.poi.terminal_arrival',
+    TERMINAL_PROXIMITY_ARRIVAL: 'shipment_tracking.tracking_job.poi.terminal_proximity_arrival',
+    TERMINAL_PROXIMITY_DEPARTURE: 'shipment_tracking.tracking_job.poi.terminal_departure',
+    WAYPOINT_REACHED: 'shipment_tracking.tracking_job.poi.waypoint_reached',
+  }
+  return map[eventType]
+}
+
+/**
+ * Build a reference info string for the notification body.
+ * Shows the booking number, BOL number, or container number.
+ *
+ * Format: "Booking BOOK123" or "BOL 12345" or "Container MSCU1234567"
+ */
+function buildReferenceInfo(
+  bookingNumber: string | null | undefined,
+  bolNumber: string | null | undefined,
+  containerNumber: string | null | undefined
+): string {
+  if (bookingNumber) {
+    return `Booking ${bookingNumber}`
+  }
+  if (bolNumber) {
+    return `BOL ${bolNumber}`
+  }
+  if (containerNumber) {
+    return `Container ${containerNumber}`
+  }
+  return 'Shipment'
+}
+
+export default async function handle(payload: TrackingJobPoiEventPayload, ctx: ResolverContext) {
+  try {
+    const em = ctx.resolve<EntityManager>('em')
+
+    // Get the creator of the tracking job from audit logs
+    const creatorUserId = await getTrackingJobCreator(em, payload.trackingJobId, payload.tenantId)
+
+    if (!creatorUserId) {
+      console.info(
+        `[poi-notification] Skipping notification - no creator found for tracking job ${payload.trackingJobId}`
+      )
+      return
+    }
+
+    // Find the notification type definition
+    const notificationType = mapEventTypeToNotificationType(payload.eventType)
+    const typeDef = notificationTypes.find((t) => t.type === notificationType)
+
+    if (!typeDef) {
+      console.warn(`[poi-notification] No notification type found for event: ${payload.eventType}`)
+      return
+    }
+
+    // Build reference info string (e.g., "Booking BOOK123")
+    const referenceInfo = buildReferenceInfo(
+      payload.bookingNumber,
+      payload.bolNumber,
+      payload.containerNumber
+    )
+
+    // Build notification input
+    const notificationInput = buildNotificationFromType(typeDef, {
+      recipientUserId: creatorUserId,
+      bodyVariables: {
+        vesselName: payload.vesselName,
+        location: payload.poiCode ?? 'unknown location',
+        referenceInfo,
+      },
+      sourceEntityType: 'shipment_tracking:shipment',
+      sourceEntityId: payload.shipmentId,
+      linkHref: `/backend/shipment-tracking?shipment=${payload.shipmentId}`,
+    })
+
+    // Create the notification
+    const notificationService = resolveNotificationService(ctx)
+    await notificationService.create(notificationInput, {
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId ?? null,
+    })
+
+    console.info(
+      `[poi-notification] Created notification for tracking job ${payload.trackingJobId} ` +
+        `(event: ${payload.eventType}, recipient: ${creatorUserId}, ref: ${referenceInfo})`
+    )
+  } catch (error) {
+    console.error('[poi-notification] Failed to process POI event notification:', error)
+  }
+}

package/src/modules/shipment_tracking/subscribers/poi-event-webhook-dispatch.ts

@@ -0,0 +1,94 @@
+/**
+ * POI Event Webhook Dispatcher
+ *
+ * Handles POI proximity events and dispatches webhooks to registered endpoints.
+ */
+
+import type { ProximityEventType } from '../lib/poi-types'
+
+export const metadata = {
+  event: 'shipment_tracking.poi.*',
+  persistent: true,
+  id: 'shipment_tracking:poi-event-webhook-dispatch',
+}
+
+type PoiEventPayload = {
+  shipmentId: string
+  trackingEventId: string
+  organizationId: string
+  tenantId: string
+  vesselName: string
+  vesselMmsi: number
+  vesselImo: string | null
+  eventType: ProximityEventType
+  poiCode: string | null
+  latitude: number
+  longitude: number
+  eventDateTime: string
+  distanceToPoiMeters: number | null
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+  eventName: string
+}
+
+type WebhookService = {
+  dispatchEvent: (params: {
+    eventType: string
+    payload: unknown
+    tenantId: string
+    organizationId: string
+  }) => Promise<void>
+}
+
+export default async function handle(payload: PoiEventPayload, ctx: ResolverContext) {
+  try {
+    const webhookService = ctx.resolve<WebhookService | undefined>('shipmentTrackingWebhookService')
+
+    if (!webhookService) {
+      console.debug('[shipment-tracking:poi-webhook] WebhookService not available, skipping dispatch')
+      return
+    }
+
+    await webhookService.dispatchEvent({
+      eventType: ctx.eventName,
+      payload: {
+        event: {
+          // IDs
+          trackingEventId: payload.trackingEventId,
+          shipmentId: payload.shipmentId,
+
+          // Event type
+          eventType: payload.eventType,
+          eventDateTime: payload.eventDateTime,
+
+          // Vessel info
+          vesselName: payload.vesselName,
+          vesselMmsi: payload.vesselMmsi,
+          vesselImo: payload.vesselImo,
+
+          // Location info
+          poiCode: payload.poiCode,
+          latitude: payload.latitude,
+          longitude: payload.longitude,
+          distanceToPoiMeters: payload.distanceToPoiMeters,
+
+          // Source identifier
+          source: 'ais',
+        },
+      },
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId,
+    })
+
+    console.debug(
+      `[shipment-tracking:poi-webhook] Dispatched ${ctx.eventName} for shipment ${payload.shipmentId}`
+    )
+  } catch (error) {
+    console.error(
+      `[shipment-tracking:poi-webhook] Failed to dispatch ${ctx.eventName} webhook:`,
+      error
+    )
+  }
+}

package/src/modules/shipment_tracking/subscribers/shipment-status-changed.ts

@@ -0,0 +1,41 @@
+import type { WebhookService } from '../services/webhookService'
+
+export const metadata = {
+  event: 'shipment_tracking.shipment.status_changed',
+  persistent: true,
+  id: 'shipment_tracking:shipment-status-changed',
+}
+
+type StatusChangedPayload = {
+  id: string
+  previousStatus: string
+  newStatus: string
+  tenantId: string
+  organizationId: string
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export default async function handle(payload: StatusChangedPayload, ctx: ResolverContext) {
+  try {
+    const webhookService = ctx.resolve<WebhookService>('shipmentTrackingWebhookService')
+
+    // Build full shipment payload to include in the webhook
+    const shipmentData = await webhookService.buildFullShipmentPayload(payload.id)
+
+    await webhookService.dispatchEvent({
+      eventType: 'shipment_tracking.shipment.status_changed',
+      payload: {
+        previousStatus: payload.previousStatus,
+        newStatus: payload.newStatus,
+        shipment: shipmentData,
+      },
+      tenantId: payload.tenantId,
+      organizationId: payload.organizationId,
+    })
+  } catch (error) {
+    console.error('[shipment-tracking:subscriber] Failed to dispatch status_changed webhook:', error)
+  }
+}

package/src/modules/shipment_tracking/subscribers/terminal-event-ingest.ts

@@ -0,0 +1,109 @@
+/**
+ * Terminal Event Ingest (bridge)
+ *
+ * Surfaces terminal-tracking events on the shipment-tracking timeline. Reacts
+ * to the `terminal_tracking.terminal_event.created` event (string coupling
+ * only — this module does NOT import @freighttech/terminal-tracking), finds the
+ * matching tracked Shipment by container number, and records a `source:'port'`
+ * TrackingEvent. Fully additive; no-ops when no matching shipment is tracked.
+ */
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { Shipment, TrackingEvent } from '../data/entities'
+import type { TrackingService } from '../services/trackingService'
+
+export const metadata = {
+  event: 'terminal_tracking.terminal_event.created',
+  persistent: false,
+  id: 'shipment_tracking:terminal-event-ingest',
+}
+
+type TerminalEventPayload = {
+  sourceEventId: string
+  eventType: 'EQUIPMENT' | 'TRANSPORT'
+  eventCode: string
+  eventClassifierCode?: 'ACT' | 'PLN' | 'EST' | null
+  eventDateTime: string
+  containerNumber: string
+  tenantId: string
+  organizationId: string
+  unlocode?: string | null
+  facilityCode?: string | null
+  facilityCodeListProvider?: 'SMDG' | 'BIC' | null
+  vesselName?: string | null
+  voyageNumber?: string | null
+  modeOfTransport?: 'VESSEL' | 'RAIL' | 'TRUCK' | 'BARGE' | null
+  seals?: Array<{ number: string; type?: string | null; source?: string | null }> | null
+  rawData?: Record<string, unknown> | null
+}
+
+type ResolverContext = { resolve: <T = unknown>(name: string) => T }
+
+export default async function handle(payload: TerminalEventPayload, ctx: ResolverContext) {
+  if (!payload?.containerNumber || !payload?.sourceEventId) return
+
+  const em = ctx.resolve<EntityManager>('em').fork()
+  const trackingService = ctx.resolve<TrackingService>('shipmentTrackingService')
+
+  // Scope to currently-tracked, non-delivered shipments (mirror
+  // poi-event-processor). A container number is reused across journeys over
+  // time, so without this a returned container's new-visit events would refresh
+  // and override a historic, already-delivered shipment with the same number.
+  const shipments = await em.find(
+    Shipment,
+    {
+      organizationId: payload.organizationId,
+      tenantId: payload.tenantId,
+      containerNumber: payload.containerNumber,
+      deletedAt: null,
+      isActive: true,
+      status: { $nin: ['DELIVERED'] },
+    },
+    { populate: ['trackingJob'] },
+  )
+
+  const eventDateTime = new Date(payload.eventDateTime)
+  const touchedJobs = new Map<string, Set<string>>()
+
+  for (const shipment of shipments) {
+    if (!shipment.trackingJob) continue
+
+    const exists = await em.findOne(TrackingEvent, {
+      trackingJob: shipment.trackingJob.id,
+      source: 'port',
+      sourceEventId: payload.sourceEventId,
+    })
+    if (exists) continue
+
+    const event = new TrackingEvent()
+    event.organizationId = shipment.organizationId
+    event.tenantId = shipment.tenantId
+    event.trackingJob = shipment.trackingJob
+    event.source = 'port'
+    event.sourceEventId = payload.sourceEventId
+    event.eventType = payload.eventType
+    event.eventCode = payload.eventCode
+    event.eventClassifierCode = payload.eventClassifierCode ?? 'ACT'
+    event.eventDateTime = eventDateTime
+    event.equipmentReference = payload.containerNumber
+    event.locationUnlocode = payload.unlocode ?? null
+    event.facilityCode = payload.facilityCode ?? null
+    event.facilityCodeListProvider = payload.facilityCodeListProvider ?? null
+    event.vesselName = payload.vesselName ?? null
+    event.voyageNumber = payload.voyageNumber ?? null
+    event.modeOfTransport = payload.modeOfTransport ?? null
+    event.seals = payload.seals ?? null
+    event.rawData = payload.rawData ?? null
+    em.persist(event)
+
+    const set = touchedJobs.get(shipment.trackingJob.id) ?? new Set<string>()
+    set.add(shipment.id)
+    touchedJobs.set(shipment.trackingJob.id, set)
+  }
+
+  if (touchedJobs.size === 0) return
+  await em.flush()
+
+  for (const [jobId, shipmentIds] of touchedJobs) {
+    await trackingService.refreshShipmentsFromEvents(em, jobId, Array.from(shipmentIds))
+  }
+}

package/src/modules/shipment_tracking/subscribers/tracking-job-initial-poll.ts

@@ -0,0 +1,53 @@
+/**
+ * Tracking Job Initial Poll Subscriber
+ *
+ * Triggers an immediate poll when a new tracking job is created.
+ * This ensures the carrier API is queried right away instead of waiting
+ * for the next scheduled poll interval.
+ */
+
+import type { TrackingService } from '../services/trackingService'
+
+export const metadata = {
+  event: 'shipment_tracking.tracking_job.created',
+  persistent: false, // In-process, immediate execution
+  id: 'shipment_tracking:tracking-job-initial-poll',
+}
+
+type TrackingJobCreatedPayload = {
+  id: string
+  carrierCode: string
+  referenceType: string
+  referenceValue: string
+  tenantId: string
+  organizationId: string
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export default async function handle(payload: TrackingJobCreatedPayload, ctx: ResolverContext) {
+  const trackingService = ctx.resolve<TrackingService>('shipmentTrackingService')
+
+  console.log('[shipment-tracking] Triggering initial poll for new tracking job:', {
+    jobId: payload.id,
+    carrierCode: payload.carrierCode,
+    reference: `${payload.referenceType}:${payload.referenceValue}`,
+  })
+
+  try {
+    const result = await trackingService.pollTrackingJob(payload.id)
+
+    console.log('[shipment-tracking] Initial poll completed:', {
+      jobId: payload.id,
+      newEvents: result.newEvents,
+      shipmentsCreated: result.shipmentsCreated,
+      shipmentsUpdated: result.shipmentsUpdated,
+    })
+  } catch (error) {
+    // Log error but don't rethrow - the job is created and will be polled on schedule
+    // Errors are already recorded in the job's errorHistory by pollTrackingJob
+    console.error('[shipment-tracking] Initial poll failed for job:', payload.id, error)
+  }
+}

package/src/modules/shipment_tracking/subscribers/tracking-job-webhook-dispatch.ts

@@ -0,0 +1,50 @@
+/**
+ * Tracking Job Event Handler
+ *
+ * NOTE: As of DCSA T&T compliance update, tracking_job events are marked as
+ * internal events (excludeFromTriggers: true) and are NOT dispatched to
+ * external webhooks. These events are for internal system monitoring only.
+ *
+ * This subscriber remains for internal audit logging but does not dispatch
+ * webhooks to external consumers. External consumers should subscribe to
+ * DCSA-compliant events like:
+ * - shipment_tracking.transport.* (departed, arrived, eta_updated, etc.)
+ * - shipment_tracking.equipment.* (loaded, discharged, gate_in, etc.)
+ * - shipment_tracking.shipment.* (created, updated, status_changed, etc.)
+ */
+
+export const metadata = {
+  event: 'shipment_tracking.tracking_job.*',
+  persistent: true,
+  id: 'shipment_tracking:tracking-job-webhook-dispatch',
+}
+
+type TrackingJobEventPayload = {
+  id: string
+  shipmentId?: string
+  carrierCode?: string
+  tenantId: string
+  organizationId: string
+}
+
+type ResolverContext = {
+  resolve: <T = unknown>(name: string) => T
+  eventName: string
+}
+
+export default async function handle(payload: TrackingJobEventPayload, ctx: ResolverContext) {
+  // Extract the action from the event name (e.g., "created", "updated", "failed")
+  const eventParts = ctx.eventName.split('.')
+  const action = eventParts[eventParts.length - 1]
+
+  // Internal logging only - no webhook dispatch for tracking_job events
+  // These are internal system events per DCSA compliance requirements
+  console.debug(`[shipment-tracking:internal] Tracking job event: ${action}`, {
+    jobId: payload.id,
+    shipmentId: payload.shipmentId,
+    carrierCode: payload.carrierCode,
+  })
+
+  // NOTE: Webhook dispatch removed - tracking_job events are internal only
+  // External consumers should subscribe to DCSA-compliant transport/equipment events
+}

package/src/modules/shipment_tracking/tables/index.ts

@@ -0,0 +1,4 @@
+import type { TableDefinition } from '@freighttech/ui/backend/dynamic-table'
+import trackingJob from './tracking_job/table'
+
+export const tables: TableDefinition[] = [trackingJob]