@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/lib/timestamp-utils.ts

@@ -0,0 +1,244 @@
+/**
+ * Multi-source timestamp utilities for shipment tracking.
+ *
+ * Supports tracking ETD/ETA/ATD/ATA from multiple sources with full history (SCD pattern).
+ * Primary value is computed using "latest update wins" strategy.
+ */
+
+export type TimestampSource = 'carrier_api' | 'manual' | 'ais' | 'port' | 'edi'
+
+export type TimestampType = 'ETD' | 'ETA' | 'ATD' | 'ATA'
+
+/**
+ * A single timestamp entry tracking value, source, and when it was recorded.
+ * Multiple entries per source are allowed (SCD - Slowly Changing Dimension pattern).
+ */
+export type ShipmentTimestampEntry = {
+  /** ISO 8601 datetime value (e.g., "2026-02-24T15:30:00") */
+  value: string
+  /** Original timezone offset (e.g., "+08:00", "-05:00", "Z") */
+  offset: string | null
+  /** Source system that provided this timestamp */
+  source: TimestampSource
+  /** When this entry was recorded/updated (ISO 8601) */
+  updatedAt: string
+  /** Optional reference to the source tracking event ID */
+  sourceEventId?: string | null
+}
+
+/**
+ * Computed primary timestamp with its metadata.
+ */
+export type ComputedTimestamp = {
+  value: Date
+  offset: string | null
+  source: TimestampSource
+  updatedAt: Date
+  sourceEventId?: string | null
+}
+
+/**
+ * Gets the latest (primary) timestamp from an array of entries.
+ * Uses "latest update wins" strategy - the entry with most recent updatedAt is primary.
+ *
+ * @param entries Array of timestamp entries or null/undefined
+ * @returns The latest entry or null if no entries
+ */
+export function getLatestTimestamp(
+  entries: ShipmentTimestampEntry[] | null | undefined,
+): ComputedTimestamp | null {
+  if (!entries?.length) return null
+
+  // Use >= to prefer later entries when updatedAt is equal.
+  // This handles the case where entries are added in the same millisecond.
+  const latest = entries.reduce((best, entry) =>
+    entry.updatedAt >= best.updatedAt ? entry : best,
+  )
+
+  return {
+    value: new Date(latest.value),
+    offset: latest.offset,
+    source: latest.source,
+    updatedAt: new Date(latest.updatedAt),
+    sourceEventId: latest.sourceEventId,
+  }
+}
+
+/**
+ * Gets the primary value as a Date, or null if no entries.
+ * Convenience wrapper around getLatestTimestamp.
+ */
+export function getPrimaryTimestampValue(
+  entries: ShipmentTimestampEntry[] | null | undefined,
+): Date | null {
+  return getLatestTimestamp(entries)?.value ?? null
+}
+
+/**
+ * Gets the primary offset, or null if no entries.
+ */
+export function getPrimaryTimestampOffset(
+  entries: ShipmentTimestampEntry[] | null | undefined,
+): string | null {
+  return getLatestTimestamp(entries)?.offset ?? null
+}
+
+/**
+ * Creates a new timestamp entry.
+ *
+ * @param value The timestamp value (Date or ISO string)
+ * @param offset Timezone offset string (e.g., "+08:00") or null
+ * @param source Source system
+ * @param sourceEventId Optional source event ID for traceability
+ * @returns A new ShipmentTimestampEntry
+ */
+export function createTimestampEntry(
+  value: Date | string,
+  offset: string | null,
+  source: TimestampSource,
+  sourceEventId?: string | null,
+): ShipmentTimestampEntry {
+  const dateValue = typeof value === 'string' ? new Date(value) : value
+
+  return {
+    value: dateValue.toISOString(),
+    offset,
+    source,
+    updatedAt: new Date().toISOString(),
+    sourceEventId: sourceEventId ?? null,
+  }
+}
+
+/**
+ * Adds a timestamp entry to an array with time-based deduplication.
+ * Deduplication: if an entry with the same value+source exists, it won't be added.
+ * Multiple entries per source with different values ARE allowed (SCD pattern).
+ *
+ * @param entries Existing entries array (will be mutated) or null
+ * @param newEntry Entry to add
+ * @returns The updated array (creates new array if input was null)
+ */
+export function addTimestampEntry(
+  entries: ShipmentTimestampEntry[] | null | undefined,
+  newEntry: ShipmentTimestampEntry,
+): ShipmentTimestampEntry[] {
+  const result = entries ? [...entries] : []
+
+  // Dedupe: check if exact same value+source combo already exists
+  const isDuplicate = result.some(
+    (e) => e.value === newEntry.value && e.source === newEntry.source,
+  )
+
+  if (!isDuplicate) {
+    result.push(newEntry)
+  }
+
+  return result
+}
+
+/**
+ * Merges extracted times into existing timestamp arrays.
+ * Used when processing tracking events to update shipment timestamps.
+ *
+ * @param current Current timestamp arrays from shipment
+ * @param extracted Newly extracted timestamps from events
+ * @param source Source of the extracted timestamps
+ * @param sourceEventId Optional source event ID
+ * @returns Updated timestamp arrays
+ */
+export function mergeExtractedTimestamps(
+  current: {
+    etdTimestamps?: ShipmentTimestampEntry[] | null
+    etaTimestamps?: ShipmentTimestampEntry[] | null
+    atdTimestamps?: ShipmentTimestampEntry[] | null
+    ataTimestamps?: ShipmentTimestampEntry[] | null
+  },
+  extracted: {
+    etd?: Date | null
+    etdOffset?: string | null
+    eta?: Date | null
+    etaOffset?: string | null
+    atd?: Date | null
+    atdOffset?: string | null
+    ata?: Date | null
+    ataOffset?: string | null
+  },
+  source: TimestampSource,
+  sourceEventId?: string | null,
+): {
+  etdTimestamps: ShipmentTimestampEntry[] | null
+  etaTimestamps: ShipmentTimestampEntry[] | null
+  atdTimestamps: ShipmentTimestampEntry[] | null
+  ataTimestamps: ShipmentTimestampEntry[] | null
+  changed: boolean
+} {
+  let changed = false
+  let etdTimestamps = current.etdTimestamps ?? null
+  let etaTimestamps = current.etaTimestamps ?? null
+  let atdTimestamps = current.atdTimestamps ?? null
+  let ataTimestamps = current.ataTimestamps ?? null
+
+  if (extracted.etd) {
+    const entry = createTimestampEntry(extracted.etd, extracted.etdOffset ?? null, source, sourceEventId)
+    const before = etdTimestamps?.length ?? 0
+    etdTimestamps = addTimestampEntry(etdTimestamps, entry)
+    if ((etdTimestamps?.length ?? 0) > before) changed = true
+  }
+
+  if (extracted.eta) {
+    const entry = createTimestampEntry(extracted.eta, extracted.etaOffset ?? null, source, sourceEventId)
+    const before = etaTimestamps?.length ?? 0
+    etaTimestamps = addTimestampEntry(etaTimestamps, entry)
+    if ((etaTimestamps?.length ?? 0) > before) changed = true
+  }
+
+  if (extracted.atd) {
+    const entry = createTimestampEntry(extracted.atd, extracted.atdOffset ?? null, source, sourceEventId)
+    const before = atdTimestamps?.length ?? 0
+    atdTimestamps = addTimestampEntry(atdTimestamps, entry)
+    if ((atdTimestamps?.length ?? 0) > before) changed = true
+  }
+
+  if (extracted.ata) {
+    const entry = createTimestampEntry(extracted.ata, extracted.ataOffset ?? null, source, sourceEventId)
+    const before = ataTimestamps?.length ?? 0
+    ataTimestamps = addTimestampEntry(ataTimestamps, entry)
+    if ((ataTimestamps?.length ?? 0) > before) changed = true
+  }
+
+  return {
+    etdTimestamps,
+    etaTimestamps,
+    atdTimestamps,
+    ataTimestamps,
+    changed,
+  }
+}
+
+/**
+ * Checks if a timestamp array has any entries.
+ */
+export function hasTimestamps(entries: ShipmentTimestampEntry[] | null | undefined): boolean {
+  return !!entries && entries.length > 0
+}
+
+/**
+ * Gets all timestamps from a specific source.
+ */
+export function getTimestampsBySource(
+  entries: ShipmentTimestampEntry[] | null | undefined,
+  source: TimestampSource,
+): ShipmentTimestampEntry[] {
+  if (!entries) return []
+  return entries.filter((e) => e.source === source)
+}
+
+/**
+ * Gets the history of timestamp changes, sorted by updatedAt (oldest first).
+ */
+export function getTimestampHistory(
+  entries: ShipmentTimestampEntry[] | null | undefined,
+): ShipmentTimestampEntry[] {
+  if (!entries) return []
+  return [...entries].sort((a, b) => a.updatedAt.localeCompare(b.updatedAt))
+}

package/src/modules/shipment_tracking/lib/vessel-api.ts

@@ -0,0 +1,299 @@
+/**
+ * Vessel API client for fetching real-time vessel position and trace data.
+ *
+ * The base URL is deployment-specific and MUST be provided via the
+ * `NEXT_PUBLIC_VESSEL_API_URL` environment variable. There is no default: when
+ * it is unset the vessel/trace/POI calls throw a clear "not configured" error
+ * and the map features that depend on them are simply unavailable.
+ */
+
+// ─── Types ───────────────────────────────────────────────────
+
+export interface VesselDimensions {
+  a: number
+  b: number
+  c: number
+  d: number
+}
+
+export interface PortInfo {
+  locode: string
+  name: string
+  city: string
+  country: string
+}
+
+export interface Position {
+  lat: number
+  lng: number
+}
+
+export type VesselStatus = 'AT_SEA' | 'IN_PORT'
+export type PoiType = 'PORT' | 'TERMINAL' | 'WAYPOINT' | 'PORT_GEOMETRIC_CENTER'
+
+export interface VesselInfo {
+  imo: number
+  mmsi: number | null
+  name: string
+  callsign: string | null
+  shipType: string | null
+  operatorName: string | null
+  owner: string | null
+  dimensions: VesselDimensions | null
+  status: VesselStatus | null
+  lastPosition: Position | null
+  lastHeading: number | null
+  lastDestination: string | null
+  lastDestinationPort: PortInfo | null
+  currentPort: PortInfo | null
+  currentPoiCode: string | null
+  currentPoiType: PoiType | null
+  isStationary: boolean
+  updatedAt: string
+}
+
+export type TraceEventType =
+  | 'POSITION_UPDATE'
+  | 'PORT_ARRIVAL'
+  | 'PORT_DEPARTURE'
+  | 'TERMINAL_ARRIVAL'
+  | 'TERMINAL_DEPARTURE'
+  | 'DESTINATION_CHANGE'
+
+export interface TracePoint {
+  lat: number
+  lng: number
+  speed: number | null
+  heading: number | null
+  eventType: TraceEventType
+  destination: string | null
+  timestamp: string
+}
+
+export interface BoundingBox {
+  north: number
+  south: number
+  east: number
+  west: number
+}
+
+/**
+ * A point of interest (port, terminal, waypoint, or port geometric center) returned by the
+ * vessel-api `/poi` endpoint, modeled as a circle (center + radius) ready to draw on a map.
+ */
+export interface PoiInfo {
+  code: string
+  locode: string
+  type: PoiType
+  center: Position
+  radiusMeters: number
+  portName: string | null
+  terminalName: string | null
+  city: string | null
+  country: string | null
+  /** Maritime region name in Polish (waypoints; may fall back to English). */
+  regionNamePl: string | null
+  /** Maritime region name in English. */
+  regionNameEn: string | null
+}
+
+export interface PoiListResponse {
+  pois: PoiInfo[]
+  count: number
+  limit: number
+  /** Present only when a bounding-box filter was applied. */
+  bounds?: BoundingBox
+  /** Present only when a type filter was applied. */
+  type?: PoiType
+}
+
+export interface TimeRange {
+  from?: string  // ISO 8601 date
+  to?: string    // ISO 8601 date
+}
+
+export interface VesselResponse {
+  vessel: VesselInfo
+}
+
+export interface TraceResponse {
+  vessel: {
+    imo: number
+    mmsi: number | null
+    name: string
+  }
+  trace: TracePoint[]
+  count: number
+  limit: number
+  bounds?: BoundingBox
+  timeRange?: TimeRange
+}
+
+// ─── Configuration ───────────────────────────────────────────
+
+function vesselApiBaseUrl(): string {
+  const baseUrl = process.env.NEXT_PUBLIC_VESSEL_API_URL || ''
+  if (!baseUrl) {
+    throw new Error(
+      'Vessel API is not configured — set NEXT_PUBLIC_VESSEL_API_URL to your vessel-tracking API base URL'
+    )
+  }
+  return baseUrl.replace(/\/+$/, '')
+}
+
+// ─── API Functions ───────────────────────────────────────────
+
+/**
+ * Fetch vessel information by IMO number or MMSI.
+ *
+ * @param imoOrMmsi - IMO number (7 digits) or MMSI (9 digits)
+ * @returns Vessel info or null if not found
+ */
+export async function fetchVessel(imoOrMmsi: number | string): Promise<VesselInfo | null> {
+  const id = typeof imoOrMmsi === 'string' ? imoOrMmsi : String(imoOrMmsi)
+
+  try {
+    const response = await fetch(`${vesselApiBaseUrl()}/vessel/${encodeURIComponent(id)}`)
+
+    if (response.status === 404) {
+      return null
+    }
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Unknown error' }))
+      throw new Error(error.error || `HTTP ${response.status}`)
+    }
+
+    const data: VesselResponse = await response.json()
+    return data.vessel
+  } catch (error) {
+    console.error('[vessel-api] Failed to fetch vessel:', error)
+    throw error
+  }
+}
+
+/**
+ * Fetch vessel trace (position history) with optional bounding box and time filters.
+ *
+ * @param imoOrMmsi - IMO number or MMSI
+ * @param bounds - Optional bounding box to filter trace points
+ * @param limit - Maximum number of points to return (default: 5000)
+ * @param timeRange - Optional time range filter (from/to in ISO 8601)
+ * @returns Trace data with array of position points
+ */
+export async function fetchVesselTrace(
+  imoOrMmsi: number | string,
+  bounds?: BoundingBox,
+  limit?: number,
+  timeRange?: TimeRange
+): Promise<TraceResponse> {
+  const id = typeof imoOrMmsi === 'string' ? imoOrMmsi : String(imoOrMmsi)
+
+  const params = new URLSearchParams()
+
+  if (bounds) {
+    params.set('north', String(bounds.north))
+    params.set('south', String(bounds.south))
+    params.set('east', String(bounds.east))
+    params.set('west', String(bounds.west))
+  }
+
+  if (limit) {
+    params.set('limit', String(limit))
+  }
+
+  if (timeRange?.from) {
+    params.set('from', timeRange.from)
+  }
+
+  if (timeRange?.to) {
+    params.set('to', timeRange.to)
+  }
+
+  const queryString = params.toString()
+  const url = `${vesselApiBaseUrl()}/vessel/${encodeURIComponent(id)}/trace${queryString ? `?${queryString}` : ''}`
+
+  try {
+    const response = await fetch(url)
+
+    if (response.status === 404) {
+      return {
+        vessel: { imo: 0, mmsi: null, name: 'Unknown' },
+        trace: [],
+        count: 0,
+        limit: limit || 5000,
+      }
+    }
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Unknown error' }))
+      throw new Error(error.error || `HTTP ${response.status}`)
+    }
+
+    const data: TraceResponse = await response.json()
+    return data
+  } catch (error) {
+    console.error('[vessel-api] Failed to fetch vessel trace:', error)
+    throw error
+  }
+}
+
+/**
+ * Fetch points of interest (ports, terminals, waypoints) as map circles, optionally
+ * constrained to a viewport bounding box and/or a single POI type.
+ *
+ * @param bounds - Optional bounding box to fetch only POIs in the current viewport
+ * @param options - Optional `type` filter and `limit` (API default/cap is 5000)
+ * @returns Array of POIs (empty on 404)
+ */
+export async function fetchPois(
+  bounds?: BoundingBox,
+  options?: { type?: PoiType; limit?: number }
+): Promise<PoiInfo[]> {
+  const params = new URLSearchParams()
+
+  if (bounds) {
+    params.set('north', String(bounds.north))
+    params.set('south', String(bounds.south))
+    params.set('east', String(bounds.east))
+    params.set('west', String(bounds.west))
+  }
+
+  if (options?.type) {
+    params.set('type', options.type)
+  }
+
+  if (options?.limit) {
+    params.set('limit', String(options.limit))
+  }
+
+  const queryString = params.toString()
+  const url = `${vesselApiBaseUrl()}/poi${queryString ? `?${queryString}` : ''}`
+
+  try {
+    const response = await fetch(url)
+
+    if (response.status === 404) {
+      return []
+    }
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Unknown error' }))
+      throw new Error(error.error || `HTTP ${response.status}`)
+    }
+
+    const data: PoiListResponse = await response.json()
+    // The API contract says `code` is unique, but the live endpoint can return the same code
+    // more than once. Dedupe by code so downstream React keys stay unique and we don't draw
+    // overlapping duplicate circles.
+    const seen = new Set<string>()
+    return (data.pois ?? []).filter((poi) => {
+      if (seen.has(poi.code)) return false
+      seen.add(poi.code)
+      return true
+    })
+  } catch (error) {
+    console.error('[vessel-api] Failed to fetch POIs:', error)
+    throw error
+  }
+}

package/src/modules/shipment_tracking/lib/vessel-cache.ts

@@ -0,0 +1,102 @@
+/**
+ * Process-global, bounded, short-TTL cache for public AIS vessel data, plus a small
+ * concurrency limiter for fanning out `fetchVessel` calls.
+ *
+ * Why this exists: the ships-map dashboard widget resolves many shipments to a handful
+ * of distinct vessels (a vessel carries several of our containers), then fetches each
+ * vessel's live position from the external `vessel-api`. That service has no batch
+ * endpoint, so we make one HTTP call per distinct IMO. To keep latency and upstream
+ * quota in check we:
+ *   - cache the public `VesselInfo` keyed by IMO (TTL ~5 min),
+ *   - bound the cache so it can't grow over the process lifetime,
+ *   - cap concurrency on the fan-out.
+ *
+ * The cache stores ONLY public maritime data (`VesselInfo` keyed by IMO) — never
+ * tenant-scoped rows — so it is safe to share across tenants. The tenant-scoped
+ * `Shipment` query and the shipment→vessel grouping are computed per request and
+ * never cached here.
+ */
+
+import { fetchVessel, type VesselInfo } from './vessel-api'
+
+// ─── Configuration ───────────────────────────────────────────
+
+const TTL_MS = 5 * 60 * 1000 // 5 minutes
+const MAX_ENTRIES = 500 // hard cap so the cache can't grow unbounded over process life
+const DEFAULT_CONCURRENCY = 8
+
+type CacheEntry = { v: VesselInfo | null; exp: number }
+
+// Module-level (process-global) cache. Keyed by IMO string.
+const cache = new Map<string, CacheEntry>()
+
+// ─── Cache ───────────────────────────────────────────────────
+
+/**
+ * Evict expired entries; if still at capacity, drop the oldest insertion (Map preserves
+ * insertion order) so the cache stays bounded.
+ */
+function evictIfNeeded(now: number): void {
+  for (const [key, entry] of cache) {
+    if (entry.exp <= now) cache.delete(key)
+  }
+  while (cache.size >= MAX_ENTRIES) {
+    const oldest = cache.keys().next().value
+    if (oldest === undefined) break
+    cache.delete(oldest)
+  }
+}
+
+/**
+ * Returns the cached `VesselInfo` for an IMO, fetching from `vessel-api` on a miss.
+ *
+ * A fetch failure is NOT cached — it propagates to the caller so the request handler can
+ * fold the IMO into `unresolvedCount` (via `Promise.allSettled`). A successful fetch that
+ * yields `null` (404 / unknown vessel) IS cached to avoid re-hitting a known-miss.
+ */
+export async function getVesselCached(imo: string): Promise<VesselInfo | null> {
+  const now = Date.now()
+  const hit = cache.get(imo)
+  if (hit && hit.exp > now) return hit.v
+
+  const vessel = await fetchVessel(imo)
+  evictIfNeeded(Date.now())
+  cache.set(imo, { v: vessel, exp: Date.now() + TTL_MS })
+  return vessel
+}
+
+/** Test-only: clear the process-global cache. */
+export function __clearVesselCache(): void {
+  cache.clear()
+}
+
+// ─── Concurrency-capped fan-out ──────────────────────────────
+
+/**
+ * Run `task` over `items` with at most `concurrency` in flight, returning results in the
+ * same order as `items`. Mirrors `Promise.allSettled` semantics: never rejects — each slot
+ * resolves to `{ status: 'fulfilled', value }` or `{ status: 'rejected', reason }`.
+ */
+export async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  task: (item: T) => Promise<R>,
+  concurrency: number = DEFAULT_CONCURRENCY,
+): Promise<PromiseSettledResult<R>[]> {
+  const results: PromiseSettledResult<R>[] = new Array(items.length)
+  let cursor = 0
+
+  async function worker(): Promise<void> {
+    while (cursor < items.length) {
+      const index = cursor++
+      try {
+        results[index] = { status: 'fulfilled', value: await task(items[index]) }
+      } catch (reason) {
+        results[index] = { status: 'rejected', reason }
+      }
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker())
+  await Promise.all(workers)
+  return results
+}

package/src/modules/shipment_tracking/lib/vessel-extraction.ts

@@ -0,0 +1,39 @@
+/**
+ * Vessel info extraction utilities for shipment tracking.
+ */
+
+export type VesselInfo = {
+  vesselName: string | null
+  vesselImo: string | null
+  voyageNumber: string | null
+}
+
+type EventWithVesselFields = {
+  vesselName?: string | null
+  vesselImo?: string | null
+  voyageNumber?: string | null
+}
+
+/**
+ * Finds the latest vessel info from a list of tracking events.
+ *
+ * For completed voyages, the last event may be a gate operation (GTOT/GTIN)
+ * that doesn't have vessel data. This function finds the latest event
+ * that has any vessel info (vesselName, vesselImo, or voyageNumber).
+ *
+ * @param events - Array of tracking events sorted by eventDateTime
+ * @returns VesselInfo from the latest event with vessel data, or null if none found
+ */
+export function findLatestVesselInfo(events: EventWithVesselFields[]): VesselInfo | null {
+  const eventWithVessel = [...events]
+    .reverse()
+    .find((e) => e.vesselName || e.vesselImo || e.voyageNumber)
+
+  if (!eventWithVessel) return null
+
+  return {
+    vesselName: eventWithVessel.vesselName ?? null,
+    vesselImo: eventWithVessel.vesselImo ?? null,
+    voyageNumber: eventWithVessel.voyageNumber ?? null,
+  }
+}