@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/events.ts

@@ -0,0 +1,122 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+/**
+ * Shipment Tracking Module Events
+ *
+ * Event Emission Granularity:
+ * ───────────────────────────────────────────────────────────────────────────────
+ * PER SHIPMENT (Container):
+ *   - Shipment CRUD/Lifecycle events are emitted once per shipment entity.
+ *   - A booking with 5 containers will trigger 5 events.
+ *   - Includes: shipment.*, transport.*, equipment.*, poi.*
+ *
+ * PER TRACKING JOB (BOL/Booking):
+ *   - Tracking job events are emitted once per tracking job, regardless of
+ *     how many containers are in the booking.
+ *   - Includes: tracking_job.*
+ *
+ * PER TRACKING EVENT (Raw Event Record):
+ *   - tracking_event.created is emitted per raw event record from carriers.
+ *   - Contains equipmentReference for the specific container.
+ *
+ * NOTE: For notifications, POI events emit per-shipment which can cause
+ * duplicate notifications for multi-container bookings. The notification
+ * subscriber should deduplicate by bookingNumber/bolNumber.
+ * ───────────────────────────────────────────────────────────────────────────────
+ */
+
+const events = [
+  // ─── Shipment CRUD ─────────────────────────────────────────────
+  // Emitted PER SHIPMENT (container) - booking with N containers = N events
+  { id: 'shipment_tracking.shipment.created', label: 'Shipment Created', entity: 'shipment', category: 'crud' },
+  { id: 'shipment_tracking.shipment.updated', label: 'Shipment Updated', entity: 'shipment', category: 'crud' },
+  { id: 'shipment_tracking.shipment.deleted', label: 'Shipment Deleted', entity: 'shipment', category: 'crud' },
+
+  // ─── Shipment Lifecycle ────────────────────────────────────────
+  // Emitted PER SHIPMENT (container) - booking with N containers = N events
+  { id: 'shipment_tracking.shipment.status_changed', label: 'Shipment Status Changed', entity: 'shipment', category: 'lifecycle' },
+  { id: 'shipment_tracking.shipment.booked', label: 'Shipment Booked', entity: 'shipment', category: 'lifecycle' },
+  { id: 'shipment_tracking.shipment.pre_arrival', label: 'Shipment Pre-Arrival', entity: 'shipment', category: 'lifecycle' },
+  { id: 'shipment_tracking.shipment.delivered', label: 'Shipment Delivered', entity: 'shipment', category: 'lifecycle' },
+
+  // ─── Transport Events (DCSA TRANSPORT) ─────────────────────────
+  // Emitted PER SHIPMENT when shipment ETA/ETD is updated
+  // Vessel/transport movement events per DCSA T&T standard
+  { id: 'shipment_tracking.transport.departed', label: 'Transport Departed', entity: 'shipment', category: 'lifecycle' },
+  { id: 'shipment_tracking.transport.arrived', label: 'Transport Arrived', entity: 'shipment', category: 'lifecycle' },
+  { id: 'shipment_tracking.transport.eta_updated', label: 'ETA Updated', entity: 'shipment', category: 'lifecycle' },
+  { id: 'shipment_tracking.transport.etd_updated', label: 'ETD Updated', entity: 'shipment', category: 'lifecycle' },
+  { id: 'shipment_tracking.transport.omitted', label: 'Port Omitted', entity: 'shipment', category: 'lifecycle' },
+
+  // ─── Equipment Events (DCSA EQUIPMENT) ─────────────────────────
+  // Emitted PER CONTAINER - tied to specific equipmentReference
+  // Container handling events per DCSA T&T standard
+  { id: 'shipment_tracking.equipment.loaded', label: 'Container Loaded', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.equipment.discharged', label: 'Container Discharged', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.equipment.gate_in', label: 'Container Gate In', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.equipment.gate_out', label: 'Container Gate Out', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.equipment.available_pickup', label: 'Available for Pickup', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.equipment.customs_released', label: 'Customs Released', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.equipment.inspected', label: 'Container Inspected', entity: 'tracking_event', category: 'lifecycle' },
+
+  // NOTE: air (mode='air') milestones are NOT separate events. The ShipsGo
+  // mapper translates air movements onto the DCSA departure/arrival/delivery
+  // codes, so an air shipment already emits the shared transport.*/shipment.*
+  // lifecycle events the notification system consumes. Dedicated air.* events
+  // would need their own emit path + subscribers and would double-fire; add
+  // them only when a consumer genuinely needs the RCS/MAN/RCF granularity.
+
+  // ─── Tracking Events (generic) ─────────────────────────────────
+  // Emitted PER RAW EVENT from carrier API (contains equipmentReference)
+  { id: 'shipment_tracking.tracking_event.created', label: 'Tracking Event Created', entity: 'tracking_event', category: 'crud' },
+
+  // ─── Internal Events (excluded from webhook triggers) ──────────
+  // Emitted PER TRACKING JOB (BOL/Booking) - once regardless of container count
+  // Tracking jobs - internal system events
+  { id: 'shipment_tracking.tracking_job.created', label: 'Tracking Job Created', entity: 'tracking_job', category: 'crud', excludeFromTriggers: true },
+  { id: 'shipment_tracking.tracking_job.updated', label: 'Tracking Job Updated', entity: 'tracking_job', category: 'crud', excludeFromTriggers: true },
+  { id: 'shipment_tracking.tracking_job.failed', label: 'Tracking Job Failed', entity: 'tracking_job', category: 'lifecycle', excludeFromTriggers: true },
+  { id: 'shipment_tracking.tracking_job.completed', label: 'Tracking Job Completed', entity: 'tracking_job', category: 'lifecycle', excludeFromTriggers: true },
+
+  // Webhook delivery - internal infrastructure events
+  { id: 'shipment_tracking.webhook.delivery_success', label: 'Webhook Delivery Success', entity: 'webhook_delivery', category: 'lifecycle', excludeFromTriggers: true },
+  { id: 'shipment_tracking.webhook.delivery_failed', label: 'Webhook Delivery Failed', entity: 'webhook_delivery', category: 'lifecycle', excludeFromTriggers: true },
+
+  // ─── Tracking Job Poll Events ──────────────────────────────────
+  // Emitted PER TRACKING JOB
+  { id: 'shipment_tracking.tracking_job.poll_failed', label: 'Tracking Job Poll Failed', entity: 'tracking_job', category: 'lifecycle', excludeFromTriggers: true },
+
+  // ─── Tracking Job POI Events (for notifications) ───────────────
+  // Emitted PER TRACKING JOB (BOL/Booking) - once regardless of container count
+  // Used for in-app notifications to avoid duplicates for multi-container bookings
+  { id: 'shipment_tracking.tracking_job.poi.port_arrival', label: 'Tracking Job - Port Arrival', entity: 'tracking_job', category: 'lifecycle' },
+  { id: 'shipment_tracking.tracking_job.poi.port_proximity_arrival', label: 'Tracking Job - Approaching Port', entity: 'tracking_job', category: 'lifecycle' },
+  { id: 'shipment_tracking.tracking_job.poi.port_departure', label: 'Tracking Job - Port Departure', entity: 'tracking_job', category: 'lifecycle' },
+  { id: 'shipment_tracking.tracking_job.poi.terminal_arrival', label: 'Tracking Job - Terminal Arrival', entity: 'tracking_job', category: 'lifecycle' },
+  { id: 'shipment_tracking.tracking_job.poi.terminal_proximity_arrival', label: 'Tracking Job - Approaching Terminal', entity: 'tracking_job', category: 'lifecycle' },
+  { id: 'shipment_tracking.tracking_job.poi.terminal_departure', label: 'Tracking Job - Terminal Departure', entity: 'tracking_job', category: 'lifecycle' },
+  { id: 'shipment_tracking.tracking_job.poi.waypoint_reached', label: 'Tracking Job - Waypoint Reached', entity: 'tracking_job', category: 'lifecycle' },
+
+  // ─── POI Proximity Events (AIS) ─────────────────────────────────
+  // Emitted PER SHIPMENT (container) - a vessel arrival triggers N events for N containers
+  // Real-time vessel position events from AIS POI detector
+  // NOTE: Notification subscribers should deduplicate by bookingNumber/bolNumber
+  { id: 'shipment_tracking.poi.port_arrival', label: 'Vessel Port Arrival (AIS)', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.poi.port_proximity_arrival', label: 'Vessel Approaching Port (AIS)', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.poi.port_departure', label: 'Vessel Port Departure (AIS)', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.poi.terminal_arrival', label: 'Vessel Terminal Arrival (AIS)', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.poi.terminal_proximity_arrival', label: 'Vessel Approaching Terminal (AIS)', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.poi.terminal_departure', label: 'Vessel Terminal Departure (AIS)', entity: 'tracking_event', category: 'lifecycle' },
+  { id: 'shipment_tracking.poi.waypoint_reached', label: 'Vessel Waypoint Reached (AIS)', entity: 'tracking_event', category: 'lifecycle' },
+] as const
+
+export const eventsConfig = createModuleEvents({
+  moduleId: 'shipment_tracking',
+  events,
+})
+
+export const emitShipmentTrackingEvent = eventsConfig.emit
+
+export type ShipmentTrackingEventId = typeof events[number]['id']
+
+export default eventsConfig

package/src/modules/shipment_tracking/hooks/useVesselTracking.ts

@@ -0,0 +1,297 @@
+'use client'
+
+/**
+ * React hooks for vessel tracking with real-time position and trace data.
+ *
+ * Features:
+ * - useVessel: Fetch vessel info with auto-refresh
+ * - useVesselTrace: Fetch trace with viewport bounding box filter
+ * - useDebouncedBounds: Debounce map viewport changes
+ */
+
+import { useState, useEffect, useCallback, useMemo } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import {
+  fetchVessel,
+  fetchVesselTrace,
+  fetchPois,
+  type VesselInfo,
+  type TraceResponse,
+  type BoundingBox,
+  type TimeRange,
+  type PoiInfo,
+} from '../lib/vessel-api'
+
+// ─── useVessel ───────────────────────────────────────────────
+
+interface UseVesselOptions {
+  /** Enable auto-refresh (default: true) */
+  autoRefresh?: boolean
+  /** Auto-refresh interval in ms (default: 30000) */
+  refreshInterval?: number
+  /** Enable the query (default: true) */
+  enabled?: boolean
+}
+
+/**
+ * Hook to fetch vessel information by IMO number.
+ * Auto-refreshes every 30 seconds by default.
+ */
+export function useVessel(
+  vesselImo: string | null | undefined,
+  options: UseVesselOptions = {}
+) {
+  const { autoRefresh = true, refreshInterval = 30_000, enabled = true } = options
+
+  return useQuery<VesselInfo | null, Error>({
+    queryKey: ['vessel-info', vesselImo],
+    queryFn: () => fetchVessel(vesselImo!),
+    enabled: enabled && !!vesselImo,
+    staleTime: refreshInterval,
+    refetchInterval: autoRefresh ? refreshInterval : false,
+    retry: 2,
+  })
+}
+
+// ─── useDebouncedBounds ──────────────────────────────────────
+
+interface UseDebouncedBoundsResult {
+  /** Current bounds (updated immediately) */
+  bounds: BoundingBox | null
+  /** Debounced bounds (updated after delay) */
+  debouncedBounds: BoundingBox | null
+  /** Update bounds - call this on map viewport change */
+  setBounds: (bounds: BoundingBox | null) => void
+  /** Whether bounds are currently being debounced */
+  isDebouncing: boolean
+}
+
+/**
+ * Hook to debounce map viewport bounds changes.
+ * Prevents excessive API calls when user is panning/zooming.
+ *
+ * @param delay - Debounce delay in ms (default: 500)
+ */
+export function useDebouncedBounds(delay = 500): UseDebouncedBoundsResult {
+  const [bounds, setBounds] = useState<BoundingBox | null>(null)
+  const [debouncedBounds, setDebouncedBounds] = useState<BoundingBox | null>(null)
+  const [isDebouncing, setIsDebouncing] = useState(false)
+
+  useEffect(() => {
+    if (!bounds) {
+      setDebouncedBounds(null)
+      setIsDebouncing(false)
+      return
+    }
+
+    setIsDebouncing(true)
+    const timer = setTimeout(() => {
+      setDebouncedBounds(bounds)
+      setIsDebouncing(false)
+    }, delay)
+
+    return () => {
+      clearTimeout(timer)
+    }
+  }, [bounds, delay])
+
+  return { bounds, debouncedBounds, setBounds, isDebouncing }
+}
+
+// ─── useVesselTrace ──────────────────────────────────────────
+
+interface UseVesselTraceOptions {
+  /** Maximum number of trace points to fetch (default: 2000) */
+  limit?: number
+  /** Stale time in ms (default: 60000) */
+  staleTime?: number
+  /** Enable the query (default: true) */
+  enabled?: boolean
+  /** Start time filter (ISO 8601) - limits trace to events after this date */
+  from?: string
+}
+
+/**
+ * Hook to fetch vessel trace (position history) within a bounding box.
+ * Only fetches when bounds are provided (debounce with useDebouncedBounds).
+ */
+export function useVesselTrace(
+  vesselImo: string | null | undefined,
+  bounds: BoundingBox | null,
+  options: UseVesselTraceOptions = {}
+) {
+  const { limit = 2000, staleTime = 60_000, enabled = true, from } = options
+
+  // Memoize bounds to prevent unnecessary refetches
+  const boundsKey = useMemo(() => {
+    if (!bounds) return null
+    // Round to 3 decimal places to prevent micro-changes from triggering refetch
+    return `${bounds.north.toFixed(3)},${bounds.south.toFixed(3)},${bounds.east.toFixed(3)},${bounds.west.toFixed(3)}`
+  }, [bounds])
+
+  // Build time range if from is provided
+  const timeRange: TimeRange | undefined = from ? { from } : undefined
+
+  return useQuery<TraceResponse, Error>({
+    queryKey: ['vessel-trace', vesselImo, boundsKey, limit, from],
+    queryFn: () => fetchVesselTrace(vesselImo!, bounds ?? undefined, limit, timeRange),
+    enabled: enabled && !!vesselImo && !!bounds,
+    staleTime,
+    retry: 1,
+  })
+}
+
+// ─── usePois ─────────────────────────────────────────────────
+
+interface UsePoisOptions {
+  /** Maximum number of POIs to fetch (default: 1000) */
+  limit?: number
+  /** Stale time in ms (default: 300000 — POIs are near-static) */
+  staleTime?: number
+  /** Enable the query (default: true). Gate this on zoom to avoid clutter/over-fetch. */
+  enabled?: boolean
+}
+
+/**
+ * Hook to fetch points of interest within a bounding box.
+ * Only fetches when bounds are provided and `enabled` is true (gate on zoom level).
+ */
+export function usePois(
+  bounds: BoundingBox | null,
+  options: UsePoisOptions = {}
+) {
+  const { limit = 1000, staleTime = 300_000, enabled = true } = options
+
+  // Round bounds so micro pan/zoom doesn't re-trigger; reuses the trace pattern.
+  const boundsKey = useMemo(() => {
+    if (!bounds) return null
+    return `${bounds.north.toFixed(2)},${bounds.south.toFixed(2)},${bounds.east.toFixed(2)},${bounds.west.toFixed(2)}`
+  }, [bounds])
+
+  return useQuery<PoiInfo[], Error>({
+    queryKey: ['pois', boundsKey, limit],
+    queryFn: async () => {
+      // Waypoints are open-water grid markers — exclude them at the source. The API `type`
+      // filter is single-value, so request the real-place types in parallel and merge.
+      const results = await Promise.all(
+        (['PORT', 'TERMINAL', 'PORT_GEOMETRIC_CENTER'] as const).map((type) =>
+          fetchPois(bounds ?? undefined, { type, limit }),
+        ),
+      )
+      const seen = new Set<string>()
+      return results.flat().filter((poi) => {
+        if (seen.has(poi.code)) return false
+        seen.add(poi.code)
+        return true
+      })
+    },
+    enabled: enabled && !!bounds,
+    staleTime,
+    retry: 1,
+  })
+}
+
+// ─── useVesselTracking (combined) ────────────────────────────
+
+interface UseVesselTrackingOptions {
+  /** Auto-refresh vessel position (default: true) */
+  autoRefresh?: boolean
+  /** Vessel refresh interval in ms (default: 30000) */
+  vesselRefreshInterval?: number
+  /** Trace fetch limit (default: 2000) */
+  traceLimit?: number
+  /** Bounds debounce delay in ms (default: 500) */
+  boundsDebounceDelay?: number
+  /** Start time filter for trace (ISO 8601) - limits trace to events after this date */
+  traceFrom?: string
+  /** Fetch POIs for the current viewport (default: false) */
+  enablePois?: boolean
+  /** Max POIs to fetch per viewport (default: 1000) */
+  poiLimit?: number
+}
+
+interface UseVesselTrackingResult {
+  /** Vessel info */
+  vessel: VesselInfo | null | undefined
+  /** Whether vessel is loading */
+  isVesselLoading: boolean
+  /** Vessel fetch error */
+  vesselError: Error | null
+  /** Trace data */
+  trace: TraceResponse | undefined
+  /** Whether trace is loading */
+  isTraceLoading: boolean
+  /** Trace fetch error */
+  traceError: Error | null
+  /** Whether bounds are being debounced */
+  isDebouncing: boolean
+  /** Current viewport bounds */
+  bounds: BoundingBox | null
+  /** Update bounds (call on map viewport change) */
+  setBounds: (bounds: BoundingBox | null) => void
+  /** POIs within the current viewport (empty unless enablePois) */
+  pois: PoiInfo[] | undefined
+  /** Whether POIs are loading */
+  isPoisLoading: boolean
+}
+
+/**
+ * Combined hook for vessel tracking with map integration.
+ * Handles vessel info, trace, and debounced bounds in one hook.
+ */
+export function useVesselTracking(
+  vesselImo: string | null | undefined,
+  options: UseVesselTrackingOptions = {}
+): UseVesselTrackingResult {
+  const {
+    autoRefresh = true,
+    vesselRefreshInterval = 30_000,
+    traceLimit = 2000,
+    boundsDebounceDelay = 500,
+    traceFrom,
+    enablePois = false,
+    poiLimit = 1000,
+  } = options
+
+  const { bounds, debouncedBounds, setBounds, isDebouncing } = useDebouncedBounds(boundsDebounceDelay)
+
+  const {
+    data: vessel,
+    isLoading: isVesselLoading,
+    error: vesselError,
+  } = useVessel(vesselImo, {
+    autoRefresh,
+    refreshInterval: vesselRefreshInterval,
+  })
+
+  const {
+    data: trace,
+    isLoading: isTraceLoading,
+    error: traceError,
+  } = useVesselTrace(vesselImo, debouncedBounds, {
+    limit: traceLimit,
+    from: traceFrom,
+  })
+
+  const {
+    data: pois,
+    isLoading: isPoisLoading,
+  } = usePois(debouncedBounds, {
+    enabled: enablePois,
+    limit: poiLimit,
+  })
+
+  return {
+    vessel,
+    isVesselLoading,
+    vesselError: vesselError ?? null,
+    trace,
+    isTraceLoading,
+    traceError: traceError ?? null,
+    isDebouncing,
+    bounds,
+    setBounds,
+    pois,
+    isPoisLoading,
+  }
+}