@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/lib/dcsa-event-parser.ts

@@ -0,0 +1,163 @@
+import crypto from 'node:crypto'
+import type { CarrierFetchedEvent, DocumentReference, SealInfo } from './carrier-adapter'
+import type { TrackingEventType, TrackingEventClassifierCode } from '../data/entities'
+
+type RawDcsaEvent = Record<string, unknown>
+
+/**
+ * Parse coordinate value - handles both number and string formats from DCSA APIs.
+ * Some carriers return coordinates as strings (e.g., "54.381628"), others as numbers.
+ */
+function parseCoordinate(value: unknown): number | null {
+  if (value == null) return null
+  if (typeof value === 'number') return Number.isNaN(value) ? null : value
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (trimmed === '') return null
+    const parsed = parseFloat(trimmed)
+    return Number.isNaN(parsed) ? null : parsed
+  }
+  return null
+}
+
+type DcsaResponseShape =
+  | { events: RawDcsaEvent[] }
+  | RawDcsaEvent[]
+
+export function extractDcsaEventArray(data: unknown): RawDcsaEvent[] {
+  if (Array.isArray(data)) return data
+  if (data && typeof data === 'object' && 'events' in data && Array.isArray((data as Record<string, unknown>).events)) {
+    return (data as { events: RawDcsaEvent[] }).events
+  }
+  return []
+}
+
+/**
+ * Parses DCSA T&T v3.0 events into normalized CarrierFetchedEvent objects.
+ * Handles both flat event structure and nested metadata/payload structure.
+ */
+export function parseDcsaEvents(data: DcsaResponseShape, _carrierName: string): CarrierFetchedEvent[] {
+  const events = extractDcsaEventArray(data)
+
+  return events.map((event) => {
+    // DCSA v3.0 can have nested metadata/payload or flat structure
+    const metadata = event.metadata as Record<string, unknown> | undefined
+    const payload = event.payload as Record<string, unknown> | undefined
+    const effectiveEvent = payload ?? event // Use payload if present, otherwise use flat event
+
+    // Extract nested objects
+    const transportCall = effectiveEvent.transportCall as Record<string, unknown> | undefined
+    const vessel = transportCall?.vessel as Record<string, unknown> | undefined
+    const location = (effectiveEvent.eventLocation ??
+      transportCall?.location) as Record<string, unknown> | undefined
+    const geoLocation = location?.geoLocation as Record<string, unknown> | undefined
+    const address = location?.address as Record<string, unknown> | undefined
+    const publisher = (metadata?.publisher ?? event.publisher) as Record<string, unknown> | undefined
+
+    // ─── Event Source ──────────────────────────────────────────────
+    const sourceEventId = (metadata?.eventID ?? event.eventID ?? event.eventId ?? crypto.randomUUID()) as string
+
+    // ─── Core Event Fields ─────────────────────────────────────────
+    const eventType = (metadata?.eventType ?? event.eventType) as TrackingEventType
+    const eventCode = (effectiveEvent.equipmentEventTypeCode ??
+      effectiveEvent.transportEventTypeCode ??
+      effectiveEvent.shipmentEventTypeCode) as string
+    const eventClassifierCode = (effectiveEvent.eventClassifierCode ?? null) as TrackingEventClassifierCode | null
+    const eventDateTime = new Date((effectiveEvent.eventDateTime ?? event.eventDateTime) as string)
+
+    // ─── Document References ───────────────────────────────────────
+    const rawDocRefs = (effectiveEvent.relatedDocumentReferences ?? effectiveEvent.documentReferences) as Array<Record<string, unknown>> | undefined
+    const relatedDocumentReferences: DocumentReference[] | null = rawDocRefs?.map((ref) => ({
+      type: (ref.type ?? ref.documentReferenceType) as string,
+      value: (ref.value ?? ref.documentReferenceValue) as string,
+    })) ?? null
+
+    // ─── Seals ─────────────────────────────────────────────────────
+    const rawSeals = effectiveEvent.seals as Array<Record<string, unknown>> | undefined
+    const seals: SealInfo[] | null = rawSeals?.map((seal) => ({
+      number: (seal.sealNumber ?? seal.number) as string,
+      source: (seal.sealSource ?? seal.source) as string | null ?? null,
+      type: (seal.sealType ?? seal.type) as string | null ?? null,
+    })) ?? null
+
+    // ─── Event Created DateTime ────────────────────────────────────
+    const eventCreatedDateTimeRaw = metadata?.eventCreatedDateTime ?? event.eventCreatedDateTime
+    const eventCreatedDateTime = eventCreatedDateTimeRaw
+      ? new Date(eventCreatedDateTimeRaw as string)
+      : null
+
+    return {
+      // ─── Event Source ──────────────────────────────────────────────
+      source: 'dcsa' as const,
+      sourceEventId,
+
+      // ─── Core Event Fields ─────────────────────────────────────────
+      eventType,
+      eventCode,
+      eventClassifierCode,
+      eventDateTime,
+      eventDateTimeOffset: null, // Not typically in DCSA response, derived from datetime
+      description: (effectiveEvent.description as string) ?? null,
+      rawData: event,
+
+      // ─── Equipment Fields ──────────────────────────────────────────
+      equipmentReference: (effectiveEvent.equipmentReference as string) ?? null,
+      isoEquipmentCode: (effectiveEvent.ISOEquipmentCode as string) ?? null,
+      emptyIndicatorCode: (effectiveEvent.emptyIndicatorCode as 'EMPTY' | 'LADEN') ?? null,
+      isTransshipmentMove: (effectiveEvent.isTransshipmentMove as boolean) ?? null,
+
+      // ─── Location Fields ───────────────────────────────────────────
+      locationName: (location?.locationName as string) ?? null,
+      locationUnlocode: ((location?.UNLocationCode ?? location?.unLocationCode ?? 
+                          transportCall?.UNLocationCode ?? transportCall?.unLocationCode) as string) ?? null,
+      locationCountry: (address?.country as string) ?? null,
+      
+      // Facility code - transportCall has priority (where most carriers put it), then location
+      facilityCode: ((transportCall?.facilityCode ?? location?.facilityCode) as string) ?? null,
+      facilityCodeListProvider: ((transportCall?.facilityCodeListProvider ?? 
+                                  location?.facilityCodeListProvider) as 'SMDG' | 'BIC') ?? null,
+      facilityTypeCode: ((transportCall?.facilityTypeCode ?? effectiveEvent.facilityTypeCode ?? 
+                          location?.facilityTypeCode) as string) ?? null,
+      
+      // Address from otherFacility (full address string from DCSA)
+      facilityAddress: (transportCall?.otherFacility as string) ?? null,
+      
+      // Coordinates - check location directly (as strings), then geoLocation nested
+      latitude: parseCoordinate(location?.latitude) ?? parseCoordinate(geoLocation?.latitude),
+      longitude: parseCoordinate(location?.longitude) ?? parseCoordinate(geoLocation?.longitude),
+
+      // ─── Transport Call Fields ─────────────────────────────────────
+      transportCallReference: (transportCall?.transportCallReference as string) ?? null,
+      modeOfTransport: (transportCall?.modeOfTransport as 'VESSEL' | 'RAIL' | 'TRUCK' | 'BARGE') ?? null,
+      vesselName: ((vessel?.vesselName ?? vessel?.name) as string) ?? null,
+      vesselImo: (vessel?.vesselIMONumber as string) ?? null,
+      voyageNumber: (transportCall?.carrierExportVoyageNumber as string) ??
+        (transportCall?.exportVoyageNumber as string) ??
+        (transportCall?.importVoyageNumber as string) ??
+        (transportCall?.voyageNumber as string) ??
+        (vessel?.voyage as string) ?? null,
+      carrierServiceCode: (transportCall?.carrierServiceCode as string) ?? null,
+      carrierExportVoyageNumber: ((transportCall?.carrierExportVoyageNumber ?? transportCall?.exportVoyageNumber) as string) ?? null,
+      carrierImportVoyageNumber: ((transportCall?.carrierImportVoyageNumber ?? transportCall?.importVoyageNumber) as string) ?? null,
+      universalServiceReference: (transportCall?.universalServiceReference as string) ?? null,
+      universalExportVoyageReference: (transportCall?.universalExportVoyageReference as string) ?? null,
+      universalImportVoyageReference: (transportCall?.universalImportVoyageReference as string) ?? null,
+      portVisitReference: (transportCall?.portVisitReference as string) ?? null,
+
+      // ─── Document References ───────────────────────────────────────
+      relatedDocumentReferences,
+
+      // ─── Metadata Fields ───────────────────────────────────────────
+      eventCreatedDateTime,
+      retractedEventId: (metadata?.retractedEventID as string) ?? null,
+      publisherName: (publisher?.partyName as string) ?? _carrierName,
+      publisherRole: (metadata?.publisherRole as string) ??
+        (event.publisherRole as string) ?? null,
+
+      // ─── Additional Event Fields ───────────────────────────────────
+      delayReasonCode: (effectiveEvent.delayReasonCode as string) ?? null,
+      changeRemark: (effectiveEvent.changeRemark as string) ?? null,
+      seals,
+    }
+  })
+}

package/src/modules/shipment_tracking/lib/dcsa-params.ts

@@ -0,0 +1,14 @@
+import type { TrackingReferenceType } from '../data/entities'
+
+export function buildDcsaQueryParams(referenceValue: string, referenceType: TrackingReferenceType): string {
+  switch (referenceType) {
+    case 'container':
+      return `equipmentReference=${encodeURIComponent(referenceValue)}`
+    case 'booking':
+      return `carrierBookingReference=${encodeURIComponent(referenceValue)}`
+    case 'bol':
+      return `transportDocumentReference=${encodeURIComponent(referenceValue)}`
+    default:
+      return `transportDocumentReference=${encodeURIComponent(referenceValue)}`
+  }
+}

package/src/modules/shipment_tracking/lib/empty-return.ts

@@ -0,0 +1,122 @@
+/**
+ * Container-journey completion detection (to stop polling a finished job).
+ *
+ * A container is done when the carrier reports either:
+ *
+ * - **Empty return** (DCSA carriers) — an actual (`ACT`) empty gate-in
+ *   (`GTIN` + `emptyIndicatorCode === 'EMPTY'`). Keying on the empty flag is
+ *   unambiguous: a *laden* `GTIN` is the export-origin gate-in (see
+ *   `route-inference.ts`), so this can never fire at origin.
+ * - **Delivered to consignee** (COSCO) — an actual `DLVR` event. COSCO never
+ *   emits `GTIN`/`emptyIndicatorCode`, so it needs its own terminal signal.
+ *   `DLVR` is COSCO-exclusive (no other adapter or fixture emits it), so this
+ *   branch cannot prematurely stop a DCSA carrier. Note: we deliberately key on
+ *   the `DLVR` *event code*, not the `DELIVERED` *status* — DCSA carriers reach
+ *   `DELIVERED` via `GTOT`-at-destination (laden pickup) *before* the empty is
+ *   returned, so a status-based stop would defeat the empty-return intent.
+ *
+ * A `TrackingJob` may cover many containers (Bill of Lading / Booking Number),
+ * so a job is only complete when **every** discovered container is complete —
+ * never on the first. Pure helpers: no DI, no persistence.
+ *
+ * Backup for missing events: empty gate-in (and COSCO `DLVR`) are sometimes
+ * absent from carrier feeds, so `destinationArrivedBefore` stops a job once it
+ * has arrived at its destination port and `STALE_AFTER_ARRIVAL_DAYS` have passed.
+ */
+
+/** Minimal event shape both a fetched and a persisted `TrackingEvent` satisfy. */
+export type EmptyReturnEvent = {
+  eventType: string
+  eventCode: string
+  eventClassifierCode?: string | null
+  emptyIndicatorCode?: string | null
+  equipmentReference?: string | null
+  locationUnlocode?: string | null
+  eventDateTime?: Date | string | null
+}
+
+/** Buffer after destination arrival before we stop a job whose empty-return event never arrived. */
+export const STALE_AFTER_ARRIVAL_DAYS = 30
+const DAY_MS = 24 * 60 * 60 * 1000
+
+/** The `cutoff` for `destinationArrivedBefore`: arrivals at/before this are stale. */
+export function staleArrivalCutoff(now: Date = new Date()): Date {
+  return new Date(now.getTime() - STALE_AFTER_ARRIVAL_DAYS * DAY_MS)
+}
+
+/** An actual empty gate-in — the empty container returned to a depot (DCSA). */
+export function isEmptyGateIn(e: EmptyReturnEvent): boolean {
+  return (
+    e.eventType === 'EQUIPMENT' &&
+    e.eventCode === 'GTIN' &&
+    e.emptyIndicatorCode === 'EMPTY' &&
+    e.eventClassifierCode === 'ACT'
+  )
+}
+
+/** An actual delivery to consignee — COSCO's terminal signal (CS210 → DLVR). */
+export function isFinalDelivery(e: EmptyReturnEvent): boolean {
+  return e.eventType === 'EQUIPMENT' && e.eventCode === 'DLVR' && e.eventClassifierCode === 'ACT'
+}
+
+/** A container is done when it is returned empty (DCSA) or delivered (COSCO). */
+export function isContainerComplete(e: EmptyReturnEvent): boolean {
+  return isEmptyGateIn(e) || isFinalDelivery(e)
+}
+
+/**
+ * True when the job has ≥1 discovered container and every one has completed its
+ * journey (empty return or delivery), i.e. polling can stop.
+ */
+export function allContainersComplete(
+  events: readonly EmptyReturnEvent[],
+  containerNumbers: ReadonlySet<string>,
+): boolean {
+  if (containerNumbers.size === 0) return false
+  const complete = new Set<string>()
+  for (const e of events) {
+    if (e.equipmentReference && isContainerComplete(e)) complete.add(e.equipmentReference)
+  }
+  for (const c of containerNumbers) {
+    if (!complete.has(c)) return false
+  }
+  return true
+}
+
+/**
+ * An actual arrival at the job's destination port — `ARRI` (transport) or `DISC`
+ * (equipment), `ACT`, at the destination UNLOCODE. Destination-scoped by
+ * construction: a null/unknown destination matches nothing, so the backup can
+ * never fire for an in-transit shipment. Transshipment arrivals (different
+ * UNLOCODE) are excluded.
+ */
+export function isDestinationArrival(
+  e: EmptyReturnEvent,
+  destinationUnlocode: string | null | undefined,
+): boolean {
+  if (!destinationUnlocode) return false
+  return (
+    (e.eventCode === 'ARRI' || e.eventCode === 'DISC') &&
+    e.eventClassifierCode === 'ACT' &&
+    !!e.locationUnlocode &&
+    e.locationUnlocode.toUpperCase() === destinationUnlocode.toUpperCase()
+  )
+}
+
+/**
+ * Time-based backup: true when the shipment arrived at its destination port
+ * at/before `cutoff` (i.e. long enough ago to stop even though the empty-return
+ * event never arrived). Job-level — `ARRI` carries no container reference.
+ */
+export function destinationArrivedBefore(
+  events: readonly EmptyReturnEvent[],
+  destinationUnlocode: string | null | undefined,
+  cutoff: Date,
+): boolean {
+  for (const e of events) {
+    if (!isDestinationArrival(e, destinationUnlocode)) continue
+    const t = e.eventDateTime ? new Date(e.eventDateTime).getTime() : NaN
+    if (!Number.isNaN(t) && t <= cutoff.getTime()) return true
+  }
+  return false
+}

package/src/modules/shipment_tracking/lib/location-overrides.ts

@@ -0,0 +1,150 @@
+/**
+ * Location Override Helpers
+ *
+ * Provides lookup and application of location overrides for BIC/SMDG facility data.
+ * Overrides allow correcting incorrect terminal/facility information from BIC API.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { LocationOverride, type FacilityLocation, type FacilityCodeListProvider } from '../data/entities'
+
+export interface LocationOverrideMatch {
+  unlocode: string
+  facilityCode: string
+  facilityCodeListProvider: FacilityCodeListProvider
+  carrierCode?: string | null
+}
+
+export interface LocationOverrideScope {
+  organizationId: string
+  tenantId: string
+}
+
+/**
+ * Finds the most specific location override for a given facility.
+ *
+ * Priority order:
+ * 1. Carrier-specific override (carrierCode matches)
+ * 2. Global override (carrierCode is null)
+ *
+ * @returns The override to apply, or null if no override exists
+ */
+export async function findLocationOverride(
+  em: EntityManager,
+  match: LocationOverrideMatch,
+  scope: LocationOverrideScope
+): Promise<LocationOverride | null> {
+  if (!match.unlocode || !match.facilityCode || !match.facilityCodeListProvider) {
+    return null
+  }
+
+  // Build query conditions - carrier-specific first, then global
+  const conditions: Record<string, unknown> = {
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    unlocode: match.unlocode.toUpperCase(),
+    facilityCode: match.facilityCode,
+    facilityCodeListProvider: match.facilityCodeListProvider,
+    isActive: true,
+    deletedAt: null,
+  }
+
+  // First try carrier-specific override (normalize to uppercase)
+  if (match.carrierCode) {
+    const carrierSpecific = await em.findOne(LocationOverride, {
+      ...conditions,
+      carrierCode: match.carrierCode.toUpperCase(),
+    })
+    if (carrierSpecific) {
+      return carrierSpecific
+    }
+  }
+
+  // Fall back to global override (carrierCode is null)
+  const globalOverride = await em.findOne(LocationOverride, {
+    ...conditions,
+    carrierCode: null,
+  })
+
+  return globalOverride
+}
+
+/**
+ * Applies override data to a FacilityLocation.
+ * Only non-null fields from the override are applied.
+ * Sets source to 'manual' to indicate the data was manually overridden.
+ */
+export function applyLocationOverride(
+  location: FacilityLocation,
+  overrideData: Partial<FacilityLocation>
+): FacilityLocation {
+  const result: FacilityLocation = { ...location }
+
+  // Apply each override field if it's defined and not null
+  if (overrideData.name != null) {
+    result.name = overrideData.name
+  }
+  if (overrideData.address !== undefined) {
+    result.address = overrideData.address
+  }
+  if (overrideData.operatorName !== undefined) {
+    result.operatorName = overrideData.operatorName
+  }
+  if (overrideData.countryCode !== undefined) {
+    result.countryCode = overrideData.countryCode
+  }
+  if (overrideData.facilityTypeCode !== undefined) {
+    result.facilityTypeCode = overrideData.facilityTypeCode
+  }
+  if (overrideData.coords !== undefined) {
+    result.coords = overrideData.coords
+  }
+  // Can also override unlocode/facilityCode if needed (rare)
+  if (overrideData.unlocode !== undefined) {
+    result.unlocode = overrideData.unlocode
+  }
+  if (overrideData.facilityCode !== undefined) {
+    result.facilityCode = overrideData.facilityCode
+  }
+  if (overrideData.facilityCodeListProvider !== undefined) {
+    result.facilityCodeListProvider = overrideData.facilityCodeListProvider
+  }
+
+  // Mark as manually overridden
+  result.source = 'manual'
+
+  return result
+}
+
+/**
+ * Finds and applies location override to a FacilityLocation in one step.
+ * Returns the original location if no override exists.
+ */
+export async function applyLocationOverrideIfExists(
+  em: EntityManager,
+  location: FacilityLocation | null | undefined,
+  carrierCode: string | null | undefined,
+  scope: LocationOverrideScope
+): Promise<FacilityLocation | null> {
+  if (!location) {
+    return null
+  }
+
+  // Skip if location doesn't have required match fields
+  if (!location.unlocode || !location.facilityCode || !location.facilityCodeListProvider) {
+    return location
+  }
+
+  const override = await findLocationOverride(em, {
+    unlocode: location.unlocode,
+    facilityCode: location.facilityCode,
+    facilityCodeListProvider: location.facilityCodeListProvider,
+    carrierCode,
+  }, scope)
+
+  if (override) {
+    return applyLocationOverride(location, override.overrideData)
+  }
+
+  return location
+}

package/src/modules/shipment_tracking/lib/location-types.ts

@@ -0,0 +1,154 @@
+/**
+ * Location Types for Shipment Tracking
+ * 
+ * Rich location data combining port (UN/LOCODE) and facility/terminal details.
+ * Used for Shipment origin/destination and RouteStopEntry.
+ */
+
+// ─── Types ───────────────────────────────────────────────────
+
+/**
+ * Rich location data for origin, destination, or transshipment points.
+ * Combines port-level (UN/LOCODE) with facility-level (terminal) details.
+ */
+export interface FacilityLocation {
+  // Display name (terminal or port name)
+  name: string
+
+  // Port-level identifiers
+  unlocode: string | null          // UN/LOCODE (e.g., "PLGDN")
+  countryCode: string | null       // ISO 3166-1 alpha-2 (e.g., "PL")
+
+  // Facility/terminal identifiers (separate fields)
+  facilityCode: string | null      // SMDG/BIC code (e.g., "DCT")
+  facilityCodeListProvider: 'BIC' | 'SMDG' | null
+  facilityTypeCode: string | null  // POTE (port terminal), DEPO (depot), etc.
+
+  // Address (from DCSA otherFacility or BIC API)
+  address: string | null           // Full address string
+
+  // Coordinates
+  coords: {
+    latitude: number
+    longitude: number
+  } | null
+
+  // Operator (from BIC API enrichment only)
+  operatorName: string | null
+
+  // Source of the data
+  source: 'dcsa' | 'bic' | 'manual'
+}
+
+/**
+ * Input type for building FacilityLocation from TrackingEvent data.
+ */
+export interface LocationEventInput {
+  locationName?: string | null
+  locationUnlocode?: string | null
+  locationCountry?: string | null
+  facilityCode?: string | null
+  facilityCodeListProvider?: 'BIC' | 'SMDG' | null
+  facilityTypeCode?: string | null
+  facilityAddress?: string | null
+  latitude?: number | null
+  longitude?: number | null
+}
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+/**
+ * Determines if location data is "complete enough" to skip BIC enrichment.
+ * Complete = has name AND (coords OR address)
+ */
+export function isLocationComplete(loc: Partial<FacilityLocation> | null | undefined): boolean {
+  if (!loc) return false
+  const hasName = !!loc.name && loc.name !== 'Unknown'
+  const hasCoords = loc.coords?.latitude != null && loc.coords?.longitude != null
+  const hasAddress = !!loc.address
+
+  // Complete if we have name AND (coords OR address)
+  return hasName && (hasCoords || hasAddress)
+}
+
+/**
+ * Builds a FacilityLocation from TrackingEvent data.
+ * Extracts country code from UN/LOCODE if not provided.
+ */
+export function buildLocationFromEvent(event: LocationEventInput): FacilityLocation {
+  // Extract country code from UN/LOCODE (first 2 chars) if not provided
+  const countryCode = event.locationCountry ||
+    (event.locationUnlocode?.length === 5 ? event.locationUnlocode.slice(0, 2) : null)
+
+  return {
+    name: event.locationName || event.locationUnlocode || 'Unknown',
+    unlocode: event.locationUnlocode || null,
+    countryCode,
+    facilityCode: event.facilityCode || null,
+    facilityCodeListProvider: event.facilityCodeListProvider || null,
+    facilityTypeCode: event.facilityTypeCode || null,
+    address: event.facilityAddress || null,
+    coords: (event.latitude != null && event.longitude != null)
+      ? { latitude: event.latitude, longitude: event.longitude }
+      : null,
+    operatorName: null, // Only populated by BIC enrichment
+    source: 'dcsa',
+  }
+}
+
+/**
+ * Merges BIC enrichment data into an existing FacilityLocation.
+ * BIC provides more detailed facility names (e.g., "GDYNIA CONTAINER TERMINAL S.A.")
+ * so we prefer BIC name over generic port names from DCSA.
+ */
+export function mergeLocationWithBicData(
+  location: FacilityLocation,
+  bicData: {
+    name?: string
+    address?: string
+    coords?: { latitude: number; longitude: number }
+    operatorName?: string
+    facilityCode?: string
+    facilityCodeListProvider?: 'BIC' | 'SMDG'
+  }
+): FacilityLocation {
+  // BIC provides more descriptive terminal names, so prefer BIC name when available
+  // Only keep DCSA name if BIC doesn't provide one
+  const enrichedName = bicData.name || location.name
+
+  return {
+    ...location,
+    name: enrichedName,
+    address: location.address || bicData.address || null,
+    coords: location.coords || bicData.coords || null,
+    operatorName: location.operatorName || bicData.operatorName || null,
+    facilityCode: location.facilityCode || bicData.facilityCode || null,
+    facilityCodeListProvider: location.facilityCodeListProvider || bicData.facilityCodeListProvider || null,
+    source: bicData.name || bicData.address || bicData.coords ? 'bic' : location.source,
+  }
+}
+
+/**
+ * Creates an empty/unknown FacilityLocation with just a name/unlocode.
+ * Used when no event data is available but we need a location object.
+ */
+export function createBasicLocation(
+  nameOrUnlocode: string,
+  unlocode?: string | null
+): FacilityLocation {
+  const actualUnlocode = unlocode || (nameOrUnlocode.length === 5 ? nameOrUnlocode : null)
+  const countryCode = actualUnlocode?.slice(0, 2) || null
+
+  return {
+    name: nameOrUnlocode,
+    unlocode: actualUnlocode,
+    countryCode,
+    facilityCode: null,
+    facilityCodeListProvider: null,
+    facilityTypeCode: null,
+    address: null,
+    coords: null,
+    operatorName: null,
+    source: 'manual',
+  }
+}