@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/lib/adapters/msc.ts

@@ -0,0 +1,223 @@
+import crypto from 'node:crypto'
+import fs, { writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import type { CarrierAdapter, CarrierFetchResult, CarrierAdapterTestResult } from '../carrier-adapter'
+import { extractDocumentReferences } from '../carrier-adapter'
+import type { TrackingReferenceType } from '../../data/entities'
+import { base64UrlEncode } from '../auth/base64url'
+import { buildDcsaQueryParams } from '../dcsa-params'
+import { parseDcsaEvents } from '../dcsa-event-parser'
+import { withCarrierApiSpan } from '../logger'
+
+// MSC's public track-and-trace events endpoint (DCSA). Overridable per carrier
+// config via `apiEndpoint`.
+const EVENTS_URL = 'https://api.tech.msc.com/msc/trackandtrace/v2.2/events'
+
+/**
+ * MSC OAuth account identity. These values are specific to the API account MSC
+ * issues to each integrator (Azure AD tenant, registered client_id and API
+ * scope) and are NOT shipped as defaults — supply them, together with the PFX
+ * certificate, through the carrier config's `authConfig`.
+ */
+type MscAuthConfig = {
+  certificate_base64: string
+  clientId: string
+  scope: string
+  tokenUrl: string
+  aud: string
+}
+
+function getAuth(authConfig: Record<string, unknown> | null | undefined): MscAuthConfig {
+  const certBase64 = authConfig?.certificate_base64 as string | undefined
+  const clientId = authConfig?.client_id as string | undefined
+  const scope = authConfig?.scope as string | undefined
+  const tokenUrl = authConfig?.token_url as string | undefined
+  const aud = (authConfig?.aud as string | undefined) || tokenUrl
+  const missing = [
+    !certBase64 && 'certificate_base64',
+    !clientId && 'client_id',
+    !scope && 'scope',
+    !tokenUrl && 'token_url',
+  ].filter(Boolean)
+  if (missing.length) {
+    throw new Error(`MSC authConfig requires: ${missing.join(', ')}`)
+  }
+  return {
+    certificate_base64: certBase64!,
+    clientId: clientId!,
+    scope: scope!,
+    tokenUrl: tokenUrl!,
+    aud: aud!,
+  }
+}
+
+function extractPfxComponents(pfxBuffer: Buffer): { privateKeyPem: string; certPem: string } {
+  const tempDir = os.tmpdir()
+  const uid = crypto.randomUUID()
+  const pfxPath = path.join(tempDir, `msc_${uid}.pfx`)
+  const certPath = path.join(tempDir, `msc_cert_${uid}.pem`)
+  const keyPath = path.join(tempDir, `msc_key_${uid}.pem`)
+
+  try {
+    fs.writeFileSync(pfxPath, pfxBuffer)
+
+    execFileSync('openssl', ['pkcs12', '-in', pfxPath, '-nokeys', '-out', certPath, '-passin', 'pass:'])
+    execFileSync('openssl', ['pkcs12', '-in', pfxPath, '-nocerts', '-nodes', '-out', keyPath, '-passin', 'pass:'])
+
+    const certPem = fs.readFileSync(certPath, 'utf8')
+    const privateKeyPem = fs.readFileSync(keyPath, 'utf8')
+
+    return { privateKeyPem, certPem }
+  } finally {
+    for (const filePath of [pfxPath, certPath, keyPath]) {
+      try { fs.unlinkSync(filePath) } catch { /* ignore cleanup errors */ }
+    }
+  }
+}
+
+function createMscJwt(auth: MscAuthConfig): string {
+  const pfxBuffer = Buffer.from(auth.certificate_base64, 'base64')
+  const { privateKeyPem, certPem } = extractPfxComponents(pfxBuffer)
+
+  // Extract the last certificate from the chain for x5t thumbprint
+  const certMatches = certPem.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g)
+  if (!certMatches?.length) {
+    throw new Error('No certificates found in PFX')
+  }
+
+  const lastCert = certMatches[certMatches.length - 1]
+  const certDerBase64 = lastCert
+    .replace(/-----BEGIN CERTIFICATE-----/g, '')
+    .replace(/-----END CERTIFICATE-----/g, '')
+    .replace(/\r?\n/g, '')
+    .trim()
+
+  const certDer = Buffer.from(certDerBase64, 'base64')
+  const sha1Hash = crypto.createHash('sha1').update(certDer).digest()
+  const x5t = base64UrlEncode(sha1Hash)
+
+  const now = Math.floor(Date.now() / 1000)
+
+  const header = { alg: 'RS256', typ: 'JWT', x5t }
+  const payload = {
+    aud: auth.aud,
+    exp: now + 120,
+    iss: auth.clientId,
+    jti: crypto.randomUUID(),
+    nbf: now,
+    sub: auth.clientId,
+  }
+
+  const encodedHeader = base64UrlEncode(JSON.stringify(header))
+  const encodedPayload = base64UrlEncode(JSON.stringify(payload))
+  const unsignedToken = `${encodedHeader}.${encodedPayload}`
+
+  const sign = crypto.createSign('RSA-SHA256')
+  sign.update(unsignedToken)
+  const signature = sign.sign(privateKeyPem)
+  const encodedSignature = base64UrlEncode(signature)
+
+  return `${unsignedToken}.${encodedSignature}`
+}
+
+async function authenticate(auth: MscAuthConfig): Promise<string> {
+  return withCarrierApiSpan(
+    { carrierCode: 'msc', operation: 'authenticate' },
+    async (span) => {
+      const jwt = createMscJwt(auth)
+
+      const body = new URLSearchParams({
+        client_id: auth.clientId,
+        client_assertion: jwt,
+        client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+        scope: auth.scope,
+        grant_type: 'client_credentials',
+      })
+
+      const response = await fetch(auth.tokenUrl, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${jwt}`,
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: body.toString(),
+      })
+
+      span.setAttribute('http.status_code', response.status)
+
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => 'unknown')
+        throw new Error(`MSC token request failed (${response.status}): ${errorText}`)
+      }
+
+      const data = await response.json() as { access_token: string }
+      return data.access_token
+    },
+  )
+}
+
+export class MscAdapter implements CarrierAdapter {
+  readonly carrierCode = 'msc'
+  readonly supportedReferenceTypes: TrackingReferenceType[] = ['container', 'booking', 'bol']
+
+  async fetchEvents(input: {
+    referenceType: TrackingReferenceType
+    referenceValue: string
+    apiEndpoint?: string | null
+    authConfig?: Record<string, unknown> | null
+  }): Promise<CarrierFetchResult> {
+    return withCarrierApiSpan(
+      {
+        carrierCode: this.carrierCode,
+        operation: 'fetchEvents',
+        referenceType: input.referenceType,
+        referenceValue: input.referenceValue,
+      },
+      async (span) => {
+        const auth = getAuth(input.authConfig)
+        const token = await authenticate(auth)
+        const params = buildDcsaQueryParams(input.referenceValue, input.referenceType)
+        const url = `${input.apiEndpoint || EVENTS_URL}?${params}`
+
+        const response = await fetch(url, {
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+          },
+        })
+
+        span.setAttribute('http.status_code', response.status)
+
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => 'unknown')
+          throw new Error(`MSC API error (${response.status}): ${errorText}`)
+        }
+
+        const data = await response.json()
+        const events = parseDcsaEvents(data, 'MSC')
+
+        const { bookingNumber, bolNumber } = extractDocumentReferences(events)
+
+        span.setAttribute('events.count', events.length)
+        return { events, bookingNumber, bolNumber }
+      },
+    )
+  }
+
+  async testConnection(input: {
+    apiEndpoint?: string | null
+    authConfig?: Record<string, unknown> | null
+  }): Promise<CarrierAdapterTestResult> {
+    const start = Date.now()
+    try {
+      const auth = getAuth(input.authConfig)
+      await authenticate(auth)
+      return { success: true, message: 'MSC authentication successful', latencyMs: Date.now() - start }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      return { success: false, message: `MSC connection failed: ${message}`, latencyMs: Date.now() - start }
+    }
+  }
+}

package/src/modules/shipment_tracking/lib/adapters/zim.ts

@@ -0,0 +1,106 @@
+import type { CarrierAdapter, CarrierFetchResult, CarrierAdapterTestResult } from '../carrier-adapter'
+import { extractDocumentReferences } from '../carrier-adapter'
+import type { TrackingReferenceType } from '../../data/entities'
+import { fetchOAuthToken } from '../auth/oauth-client'
+import { buildDcsaQueryParams } from '../dcsa-params'
+import { parseDcsaEvents } from '../dcsa-event-parser'
+import { withCarrierApiSpan } from '../logger'
+
+const TOKEN_URL = 'https://apigw.zim.com/authorize/v1'
+const EVENTS_URL = 'https://apigw.zim.com/trackAndTrace/v1'
+
+type ZimAuthConfig = {
+  client_id: string
+  client_secret: string
+  subscription_key: string
+}
+
+function getAuth(authConfig: Record<string, unknown> | null | undefined): ZimAuthConfig {
+  const clientId = authConfig?.client_id as string | undefined
+  const clientSecret = authConfig?.client_secret as string | undefined
+  const subscriptionKey = authConfig?.subscription_key as string | undefined
+  if (!clientId || !clientSecret || !subscriptionKey) {
+    throw new Error('ZIM authConfig requires client_id, client_secret, and subscription_key')
+  }
+  return { client_id: clientId, client_secret: clientSecret, subscription_key: subscriptionKey }
+}
+
+async function authenticate(auth: ZimAuthConfig): Promise<string> {
+  return withCarrierApiSpan(
+    { carrierCode: 'zim', operation: 'authenticate' },
+    async (span) => {
+      const token = await fetchOAuthToken({
+        tokenUrl: TOKEN_URL,
+        clientId: auth.client_id,
+        clientSecret: auth.client_secret,
+        authMethod: 'body',
+        extraBody: { scope: 'tracing' },
+      })
+      return token
+    },
+  )
+}
+
+export class ZimAdapter implements CarrierAdapter {
+  readonly carrierCode = 'zim'
+  readonly supportedReferenceTypes: TrackingReferenceType[] = ['container', 'booking', 'bol']
+
+  async fetchEvents(input: {
+    referenceType: TrackingReferenceType
+    referenceValue: string
+    apiEndpoint?: string | null
+    authConfig?: Record<string, unknown> | null
+  }): Promise<CarrierFetchResult> {
+    return withCarrierApiSpan(
+      {
+        carrierCode: this.carrierCode,
+        operation: 'fetchEvents',
+        referenceType: input.referenceType,
+        referenceValue: input.referenceValue,
+      },
+      async (span) => {
+        const auth = getAuth(input.authConfig)
+        const token = await authenticate(auth)
+        const params = buildDcsaQueryParams(input.referenceValue, input.referenceType)
+        const url = `${input.apiEndpoint || EVENTS_URL}?${params}`
+
+        const response = await fetch(url, {
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Ocp-Apim-Subscription-Key': auth.subscription_key,
+            'Content-Type': 'application/json',
+          },
+        })
+
+        span.setAttribute('http.status_code', response.status)
+
+        if (!response.ok) {
+          const errorText = await response.text().catch(() => 'unknown')
+          throw new Error(`ZIM API error (${response.status}): ${errorText}`)
+        }
+
+        const data = await response.json()
+        const events = parseDcsaEvents(data, 'ZIM')
+        const { bookingNumber, bolNumber } = extractDocumentReferences(events)
+
+        span.setAttribute('events.count', events.length)
+        return { events, bookingNumber, bolNumber }
+      },
+    )
+  }
+
+  async testConnection(input: {
+    apiEndpoint?: string | null
+    authConfig?: Record<string, unknown> | null
+  }): Promise<CarrierAdapterTestResult> {
+    const start = Date.now()
+    try {
+      const auth = getAuth(input.authConfig)
+      await authenticate(auth)
+      return { success: true, message: 'ZIM authentication successful', latencyMs: Date.now() - start }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      return { success: false, message: `ZIM connection failed: ${message}`, latencyMs: Date.now() - start }
+    }
+  }
+}

package/src/modules/shipment_tracking/lib/audit-helpers.ts

@@ -0,0 +1,29 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { ActionLog } from '@open-mercato/core/modules/audit_logs/data/entities'
+
+/**
+ * Get the user ID of who created a tracking job by querying audit logs.
+ *
+ * This is used for notifications where we need to notify the user who created
+ * the tracking job, but the TrackingJob entity doesn't store createdByUserId.
+ */
+export async function getTrackingJobCreator(
+  em: EntityManager,
+  trackingJobId: string,
+  tenantId: string,
+): Promise<string | null> {
+  const createLog = await em.findOne(
+    ActionLog,
+    {
+      tenantId,
+      resourceKind: 'shipment_tracking.tracking_job',
+      resourceId: trackingJobId,
+      commandId: 'shipment_tracking.tracking_job.create',
+      executionState: 'done',
+      deletedAt: null,
+    },
+    { orderBy: { createdAt: 'asc' } },
+  )
+
+  return createLog?.actorUserId ?? null
+}

package/src/modules/shipment_tracking/lib/auth/base64url.ts

@@ -0,0 +1,4 @@
+export function base64UrlEncode(data: string | Buffer): string {
+  const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data)
+  return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}

package/src/modules/shipment_tracking/lib/auth/oauth-client.ts

@@ -0,0 +1,53 @@
+type OAuthConfig = {
+  tokenUrl: string
+  clientId: string
+  clientSecret: string
+  scope?: string
+  extraHeaders?: Record<string, string>
+  extraBody?: Record<string, string>
+  authMethod?: 'body' | 'basic'
+}
+
+export async function fetchOAuthToken(config: OAuthConfig): Promise<string> {
+  const { tokenUrl, clientId, clientSecret, scope, extraHeaders, extraBody, authMethod = 'body' } = config
+
+  const body = new URLSearchParams({ grant_type: 'client_credentials' })
+
+  if (authMethod === 'body') {
+    body.set('client_id', clientId)
+    body.set('client_secret', clientSecret)
+  }
+
+  if (scope) {
+    body.set('scope', scope)
+  }
+
+  if (extraBody) {
+    for (const [key, value] of Object.entries(extraBody)) {
+      body.set(key, value)
+    }
+  }
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/x-www-form-urlencoded',
+    ...extraHeaders,
+  }
+
+  if (authMethod === 'basic') {
+    headers['Authorization'] = `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`
+  }
+
+  const response = await fetch(tokenUrl, {
+    method: 'POST',
+    headers,
+    body: body.toString(),
+  })
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => 'unknown')
+    throw new Error(`OAuth token request failed (${response.status}): ${errorText}`)
+  }
+
+  const data = await response.json() as { access_token: string }
+  return data.access_token
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Runs a function in the background without blocking the caller.
+ * Errors are logged but not propagated.
+ *
+ * Uses setImmediate to defer execution to the next event loop iteration,
+ * allowing the caller to return immediately (non-blocking).
+ *
+ * @param fn - Async function to run in background
+ * @param label - Optional label for error logging
+ */
+export function runInBackground(fn: () => Promise<void>, label?: string): void {
+  setImmediate(() => {
+    fn().catch((err) => {
+      console.error(`[background${label ? `:${label}` : ''}] Error:`, err)
+    })
+  })
+}
+
+/**
+ * Sleep helper for retry delays
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/modules/shipment_tracking/lib/bic-api-client.ts

@@ -0,0 +1,199 @@
+/**
+ * BIC Facility Code API v2 Client
+ * 
+ * Provides facility enrichment data (coordinates, addresses, operator names)
+ * from the BIC Facility Code Database.
+ * 
+ * API Documentation: https://app.swaggerhub.com/apis/BIC-ORG/Facility-Codes/2.0.1
+ */
+
+// ─── Types ───────────────────────────────────────────────────
+
+export interface BicTokenResponse {
+  accessToken: string
+  access_token: string  // Also provided for compatibility
+  accessTokenExpiresAt: string  // ISO datetime
+}
+
+export interface BicAddress {
+  street?: string
+  city?: string
+  postcode?: string
+  state?: string
+  country?: string
+}
+
+export interface BicCoordinates {
+  latitude: string   // Note: strings in BIC API, need to parse
+  longitude: string
+}
+
+export interface BicFacilityDetails {
+  name: string
+  address?: BicAddress
+  formattedAddress?: string
+  geographicalCoordinate?: BicCoordinates
+}
+
+export interface BicOperator {
+  name: string
+}
+
+export interface BicFacility {
+  code: string
+  codeProvider: 'BIC' | 'SMDG'
+  countryCode: string
+  unLocode: string
+  aliasCode?: string  // If this code is deprecated
+  codeListProviderCode?: string  // Short code for SMDG
+  operator?: BicOperator
+  facility?: BicFacilityDetails
+}
+
+export interface BicClientConfig {
+  baseUrl: string
+  username: string
+  password: string
+}
+
+// ─── Client ──────────────────────────────────────────────────
+
+export class BicApiClient {
+  private baseUrl: string
+  private username: string
+  private password: string
+  private accessToken: string | null = null
+  private tokenExpiresAt: Date | null = null
+
+  constructor(config: BicClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '')  // Remove trailing slash
+    this.username = config.username
+    this.password = config.password
+  }
+
+  /**
+   * Get OAuth2 token via Basic Auth
+   */
+  private async getToken(): Promise<string> {
+    const now = new Date()
+    // Refresh if token expires in less than 60 seconds
+    if (this.accessToken && this.tokenExpiresAt && this.tokenExpiresAt > new Date(now.getTime() + 60_000)) {
+      return this.accessToken
+    }
+
+    const credentials = Buffer.from(`${this.username}:${this.password}`).toString('base64')
+
+    const response = await fetch(`${this.baseUrl}/v2/oauth/token`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Basic ${credentials}`,
+        'Content-Type': 'application/json',
+      },
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`BIC OAuth failed: ${response.status} - ${text}`)
+    }
+
+    const data: BicTokenResponse = await response.json()
+    this.accessToken = data.accessToken || data.access_token
+    this.tokenExpiresAt = new Date(data.accessTokenExpiresAt)
+    return this.accessToken
+  }
+
+  /**
+   * Look up facility by code
+   * 
+   * @param facilityCode - The facility code (BIC: 9 chars, SMDG: varies)
+   * @param codeProvider - 'BIC' or 'SMDG'
+   * @param unlocode - Required for SMDG codes to build the full lookup code
+   * @returns Facility data or null if not found
+   */
+  async getFacility(
+    facilityCode: string,
+    codeProvider: 'BIC' | 'SMDG',
+    unlocode?: string
+  ): Promise<BicFacility | null> {
+    const token = await this.getToken()
+
+    // Build lookup code:
+    // - BIC codes are already complete (9 chars)
+    // - SMDG codes need unlocode prefix (e.g., "PLGDY" + "DCT" = "PLGDYDCT")
+    const lookupCode = codeProvider === 'SMDG' && unlocode
+      ? `${unlocode}${facilityCode}`
+      : facilityCode
+
+    const url = `${this.baseUrl}/v2/facilities/${lookupCode}?codeProvider=${codeProvider}`
+
+    const response = await fetch(url, {
+      headers: { 'Authorization': `Bearer ${token}` },
+    })
+
+    if (response.status === 404) {
+      return null
+    }
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`BIC API error: ${response.status} - ${text}`)
+    }
+
+    return response.json()
+  }
+
+  /**
+   * Test connection by fetching a token
+   * @returns true if authentication succeeds
+   */
+  async testConnection(): Promise<boolean> {
+    await this.getToken()
+    return true
+  }
+
+  // ─── Static Helpers ──────────────────────────────────────────
+
+  /**
+   * Parse coordinates from BIC response (strings to numbers)
+   */
+  static parseCoordinates(facility: BicFacility): { latitude: number; longitude: number } | null {
+    const coords = facility.facility?.geographicalCoordinate
+    if (!coords?.latitude || !coords?.longitude) return null
+
+    const lat = parseFloat(coords.latitude)
+    const lng = parseFloat(coords.longitude)
+
+    if (isNaN(lat) || isNaN(lng)) return null
+    return { latitude: lat, longitude: lng }
+  }
+
+  /**
+   * Format address from BIC response
+   */
+  static formatAddress(facility: BicFacility): string | null {
+    // Prefer formatted address if available
+    if (facility.facility?.formattedAddress) {
+      return facility.facility.formattedAddress
+    }
+
+    const addr = facility.facility?.address
+    if (!addr) return null
+
+    const parts = [addr.street, addr.city, addr.state, addr.postcode, addr.country]
+    return parts.filter(Boolean).join(', ') || null
+  }
+
+  /**
+   * Get facility name from BIC response
+   */
+  static getFacilityName(facility: BicFacility): string | null {
+    return facility.facility?.name || null
+  }
+
+  /**
+   * Get operator name from BIC response
+   */
+  static getOperatorName(facility: BicFacility): string | null {
+    return facility.operator?.name || null
+  }
+}