@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/lib/logger.ts

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

package/src/modules/shipment_tracking/lib/poi-event-processor.ts

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

package/src/modules/shipment_tracking/lib/poi-nats-config.ts

@@ -0,0 +1,134 @@
+/**
+ * NATS Configuration for POI Proximity Events
+ *
+ * Configuration for connecting to NATS server and subscribing to
+ * POI proximity events from the AIS system.
+ */
+
+import { createHash, randomUUID } from 'crypto'
+
+// ─── Configuration Interface ─────────────────────────────────
+
+export interface PoiNatsConfig {
+  /** NATS server URL (e.g., nats://localhost:4222) */
+  serverUrl: string
+
+  /** JetStream stream name containing POI events */
+  streamName: string
+
+  /** NATS subject for POI proximity events (filter within stream) */
+  subject: string
+
+  /** Unique instance identifier (derived from JWT_SECRET or explicit) */
+  instanceId: string
+
+  /** Durable consumer name for reliable message delivery (includes instanceId) */
+  consumerName: string
+
+  /** Connection name for debugging */
+  connectionName: string
+
+  /** Reconnect settings */
+  reconnect: {
+    /** Maximum reconnect attempts (-1 for infinite) */
+    maxAttempts: number
+    /** Initial delay between reconnects in ms */
+    initialDelayMs: number
+    /** Maximum delay between reconnects in ms */
+    maxDelayMs: number
+  }
+}
+
+// ─── Instance ID Generation ──────────────────────────────────
+
+/**
+ * Generate a unique instance ID for this deployment.
+ *
+ * Priority:
+ * 1. POI_NATS_INSTANCE_ID env var (explicit override)
+ * 2. Hash of JWT_SECRET (stable, unique per installation)
+ * 3. Random UUID prefix (fallback for dev/testing)
+ */
+function generateInstanceId(): string {
+  // 1. Explicit override
+  if (process.env.POI_NATS_INSTANCE_ID) {
+    return process.env.POI_NATS_INSTANCE_ID
+  }
+
+  // 2. Derive from JWT_SECRET (stable across restarts)
+  const jwtSecret = process.env.JWT_SECRET
+  if (jwtSecret) {
+    const hash = createHash('sha256').update(jwtSecret).digest('hex')
+    return hash.substring(0, 8)
+  }
+
+  // 3. Fallback to random (dev/testing only)
+  console.warn('[poi-nats] JWT_SECRET not set, using random instance ID (not stable across restarts)')
+  return randomUUID().split('-')[0]
+}
+
+// ─── Default Configuration ───────────────────────────────────
+
+const DEFAULT_RECONNECT = {
+  maxAttempts: -1, // Infinite reconnect
+  initialDelayMs: 250,
+  maxDelayMs: 5000,
+}
+
+// ─── Configuration Loader ────────────────────────────────────
+
+/**
+ * Load POI NATS configuration from environment variables.
+ *
+ * Environment variables:
+ * - POI_NATS_URL: NATS server URL (required to enable)
+ * - POI_NATS_STREAM: JetStream stream name (default: AIS_STREAM)
+ * - POI_NATS_SUBJECT: Subject filter for POI events (default: ais.ship.proximity.events)
+ * - POI_NATS_INSTANCE_ID: Unique instance identifier (default: derived from JWT_SECRET)
+ *
+ * The consumer name is auto-generated as: shipment-tracking-poi-{instanceId}
+ * This allows multiple self-hosted instances to each receive all messages independently.
+ */
+export function loadPoiNatsConfig(): PoiNatsConfig {
+  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,
+  }
+}
+
+/**
+ * Check if POI NATS integration is configured.
+ *
+ * Returns true only if POI_NATS_URL is explicitly set.
+ * When not configured, the POI subscriber will be skipped.
+ */
+export function isPoiNatsConfigured(): boolean {
+  return !!process.env.POI_NATS_URL
+}
+
+/**
+ * Validate POI NATS configuration.
+ *
+ * @throws Error if configuration is invalid
+ */
+export function validatePoiNatsConfig(config: PoiNatsConfig): void {
+  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')
+  }
+}