@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/commands/carrier-configs.ts

@@ -0,0 +1,89 @@
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CarrierConfig } from '../data/entities'
+import type { CarrierConfigCreateInput, CarrierConfigUpdateInput } from '../data/validators'
+
+function ensureScope(ctx: CommandRuntimeContext, tenantId: string, organizationId: string) {
+  if (ctx.auth?.tenantId && ctx.auth.tenantId !== tenantId) {
+    throw new Error('Tenant mismatch')
+  }
+  if (!ctx.auth?.isSuperAdmin && ctx.auth?.organizationId && ctx.auth.organizationId !== organizationId) {
+    throw new Error('Organization mismatch')
+  }
+}
+
+const createCarrierConfig: CommandHandler<CarrierConfigCreateInput, { id: string }> = {
+  id: 'shipment_tracking.carrier_config.create',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const carrierConfig = em.create(CarrierConfig, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+      carrierCode: input.carrierCode,
+      apiEndpoint: input.apiEndpoint ?? null,
+      authConfig: input.authConfig ?? null,
+      rateLimitRequests: input.rateLimitRequests ?? 60,
+      rateLimitWindowSeconds: input.rateLimitWindowSeconds ?? 60,
+      isActive: input.isActive ?? true,
+    })
+
+    await em.flush()
+
+    return { id: carrierConfig.id }
+  },
+}
+
+const updateCarrierConfig: CommandHandler<CarrierConfigUpdateInput, { id: string }> = {
+  id: 'shipment_tracking.carrier_config.update',
+
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const carrierConfig = await findOneWithDecryption(em, CarrierConfig, { id: input.id, deletedAt: null })
+    if (!carrierConfig) throw new Error('Carrier config not found')
+
+    ensureScope(ctx, carrierConfig.tenantId, carrierConfig.organizationId)
+
+    if (input.apiEndpoint !== undefined) carrierConfig.apiEndpoint = input.apiEndpoint
+    if (input.authConfig !== undefined) carrierConfig.authConfig = input.authConfig
+    if (input.rateLimitRequests !== undefined) carrierConfig.rateLimitRequests = input.rateLimitRequests
+    if (input.rateLimitWindowSeconds !== undefined) carrierConfig.rateLimitWindowSeconds = input.rateLimitWindowSeconds
+    if (input.isActive !== undefined) carrierConfig.isActive = input.isActive
+
+    await em.flush()
+
+    return { id: carrierConfig.id }
+  },
+}
+
+const deleteCarrierConfig: CommandHandler<{ id: string; tenantId: string; organizationId: string }, { id: string }> = {
+  id: 'shipment_tracking.carrier_config.delete',
+
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    // Fetch first, then validate scope (same pattern as update)
+    const carrierConfig = await findOneWithDecryption(em, CarrierConfig, {
+      id: input.id,
+      deletedAt: null,
+    })
+    if (!carrierConfig) throw new Error('Carrier config not found')
+
+    ensureScope(ctx, carrierConfig.tenantId, carrierConfig.organizationId)
+
+    carrierConfig.deletedAt = new Date()
+    await em.flush()
+
+    return { id: carrierConfig.id }
+  },
+}
+
+registerCommand(createCarrierConfig)
+registerCommand(updateCarrierConfig)
+registerCommand(deleteCarrierConfig)

package/src/modules/shipment_tracking/commands/index.ts

@@ -0,0 +1,8 @@
+import './shipments'
+import './tracking'
+import './tracking-jobs'
+import './webhooks'
+import './carrier-configs'
+import './bic-configs'
+import './shipsgo-configs'
+import './location-overrides'

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

@@ -0,0 +1,119 @@
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { LocationOverride } from '../data/entities'
+import type { LocationOverrideCreateInput, LocationOverrideUpdateInput } from '../data/validators'
+
+function ensureScope(ctx: CommandRuntimeContext, tenantId: string, organizationId: string) {
+  if (ctx.auth?.tenantId && ctx.auth.tenantId !== tenantId) {
+    throw new Error('Tenant mismatch')
+  }
+  if (!ctx.auth?.isSuperAdmin && ctx.auth?.organizationId && ctx.auth.organizationId !== organizationId) {
+    throw new Error('Organization mismatch')
+  }
+}
+
+const createLocationOverride: CommandHandler<LocationOverrideCreateInput, { id: string }> = {
+  id: 'shipment_tracking.location_override.create',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const override = em.create(LocationOverride, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+      carrierCode: input.carrierCode?.toUpperCase() ?? null,
+      unlocode: input.unlocode.toUpperCase(),
+      facilityCode: input.facilityCode,
+      facilityCodeListProvider: input.facilityCodeListProvider,
+      overrideData: input.overrideData,
+      description: input.description ?? null,
+      isActive: input.isActive ?? true,
+      createdByUserId: ctx.auth?.userId ?? null,
+      updatedByUserId: ctx.auth?.userId ?? null,
+    })
+
+    await em.flush()
+
+    return { id: override.id }
+  },
+
+  async undo({ input, ctx }) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const override = await findOneWithDecryption(em, LocationOverride, {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      unlocode: input.unlocode,
+      facilityCode: input.facilityCode,
+      facilityCodeListProvider: input.facilityCodeListProvider,
+      carrierCode: input.carrierCode ?? null,
+    })
+    if (override) {
+      em.remove(override)
+      await em.flush()
+    }
+  },
+}
+
+const updateLocationOverride: CommandHandler<LocationOverrideUpdateInput, { id: string }> = {
+  id: 'shipment_tracking.location_override.update',
+
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const override = await findOneWithDecryption(em, LocationOverride, { id: input.id })
+    if (!override) throw new Error('Location override not found')
+
+    ensureScope(ctx, override.tenantId, override.organizationId)
+
+    if (input.carrierCode !== undefined) override.carrierCode = input.carrierCode?.toUpperCase() ?? null
+    if (input.unlocode !== undefined) override.unlocode = input.unlocode.toUpperCase()
+    if (input.facilityCode !== undefined) override.facilityCode = input.facilityCode
+    if (input.facilityCodeListProvider !== undefined) override.facilityCodeListProvider = input.facilityCodeListProvider
+    if (input.overrideData !== undefined) override.overrideData = input.overrideData
+    if (input.description !== undefined) override.description = input.description
+    if (input.isActive !== undefined) override.isActive = input.isActive
+    override.updatedByUserId = ctx.auth?.userId ?? null
+
+    await em.flush()
+
+    return { id: override.id }
+  },
+}
+
+const deleteLocationOverride: CommandHandler<{ id: string; tenantId: string; organizationId: string }, { id: string }> = {
+  id: 'shipment_tracking.location_override.delete',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const override = await findOneWithDecryption(em, LocationOverride, { id: input.id })
+    if (!override) throw new Error('Location override not found')
+
+    // Soft delete
+    override.deletedAt = new Date()
+    override.updatedByUserId = ctx.auth?.userId ?? null
+    await em.flush()
+
+    return { id: input.id }
+  },
+
+  async undo({ input, ctx }) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const override = await em.findOne(LocationOverride, { id: input.id })
+    if (override) {
+      override.deletedAt = null
+      override.updatedByUserId = ctx.auth?.userId ?? null
+      await em.flush()
+    }
+  },
+}
+
+registerCommand(createLocationOverride)
+registerCommand(updateLocationOverride)
+registerCommand(deleteLocationOverride)

package/src/modules/shipment_tracking/commands/shipments.ts

@@ -0,0 +1,247 @@
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import type { EntityManager } from '@mikro-orm/core'
+import type { EventBus } from '@open-mercato/events'
+import { Shipment, TrackingJob } from '../data/entities'
+import type { ShipmentCreateInput, ShipmentUpdateInput } from '../data/validators'
+import { createTimestampEntry, addTimestampEntry } from '../lib/timestamp-utils'
+import type { TimestampSource } from '../lib/timestamp-utils'
+
+function ensureScope(ctx: CommandRuntimeContext, tenantId: string, organizationId: string) {
+  if (ctx.auth?.tenantId && ctx.auth.tenantId !== tenantId) {
+    throw new Error('Tenant mismatch')
+  }
+  if (!ctx.auth?.isSuperAdmin && ctx.auth?.organizationId && ctx.auth.organizationId !== organizationId) {
+    throw new Error('Organization mismatch')
+  }
+}
+
+const createShipment: CommandHandler<ShipmentCreateInput, { id: string }> = {
+  id: 'shipment_tracking.shipment.create',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const eventBus = ctx.container.resolve<EventBus>('eventBus')
+
+    // If trackingJobId is provided, verify it exists
+    let trackingJob: TrackingJob | null = null
+    if (input.trackingJobId) {
+      trackingJob = await em.findOne(TrackingJob, {
+        id: input.trackingJobId,
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+        deletedAt: null,
+      })
+      if (!trackingJob) throw new Error('Tracking job not found')
+    }
+
+    const shipment = em.create(Shipment, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+      trackingJob: trackingJob ?? undefined,
+      carrierCode: input.carrierCode ?? null,
+      containerNumber: input.containerNumber ?? null,
+      bookingNumber: input.bookingNumber ?? null,
+      bolNumber: input.bolNumber ?? null,
+      // Multi-source timestamp arrays
+      etdTimestamps: input.etdTimestamps ?? null,
+      etaTimestamps: input.etaTimestamps ?? null,
+      atdTimestamps: input.atdTimestamps ?? null,
+      ataTimestamps: input.ataTimestamps ?? null,
+      // Location data (JSONB)
+      originLocation: input.originLocation ?? null,
+      destinationLocation: input.destinationLocation ?? null,
+      vesselName: input.vesselName ?? null,
+      vesselImo: input.vesselImo ?? null,
+      voyageNumber: input.voyageNumber ?? null,
+      extra: input.extra ?? null,
+      createdByUserId: ctx.auth?.userId ?? null,
+    })
+
+    await em.flush()
+
+    await eventBus.emit('shipment_tracking.shipment.created', {
+      id: shipment.id,
+      containerNumber: shipment.containerNumber,
+      trackingJobId: trackingJob?.id ?? null,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+
+    return { id: shipment.id }
+  },
+
+  buildLog({ result, input }) {
+    return {
+      actionLabel: 'Create shipment',
+      resourceKind: 'shipment_tracking.shipment',
+      resourceId: result.id,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    }
+  },
+
+  async undo({ logEntry, ctx }) {
+    const shipmentId = logEntry?.resourceId
+    if (!shipmentId) return
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    // Use nativeUpdate to avoid identity map issues
+    const now = new Date()
+    await em.nativeUpdate(Shipment, { id: shipmentId, deletedAt: null }, { deletedAt: now, updatedAt: now })
+  },
+}
+
+const updateShipment: CommandHandler<ShipmentUpdateInput, { id: string }> = {
+  id: 'shipment_tracking.shipment.update',
+
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const eventBus = ctx.container.resolve<EventBus>('eventBus')
+
+    const shipment = await em.findOne(Shipment, { id: input.id, deletedAt: null })
+    if (!shipment) throw new Error('Shipment not found')
+
+    ensureScope(ctx, shipment.tenantId, shipment.organizationId)
+
+    const previousStatus = shipment.status
+
+    // Handle trackingJobId change
+    if (input.trackingJobId !== undefined) {
+      if (input.trackingJobId === null) {
+        shipment.trackingJob = null
+      } else {
+        const trackingJob = await em.findOne(TrackingJob, {
+          id: input.trackingJobId,
+          tenantId: shipment.tenantId,
+          organizationId: shipment.organizationId,
+          deletedAt: null,
+        })
+        if (!trackingJob) throw new Error('Tracking job not found')
+        shipment.trackingJob = trackingJob
+      }
+    }
+
+    if (input.carrierCode !== undefined) shipment.carrierCode = input.carrierCode
+    if (input.containerNumber !== undefined) shipment.containerNumber = input.containerNumber
+    if (input.bookingNumber !== undefined) shipment.bookingNumber = input.bookingNumber
+    if (input.bolNumber !== undefined) shipment.bolNumber = input.bolNumber
+    if (input.status !== undefined) shipment.status = input.status
+
+    // Multi-source timestamp arrays - can replace entire arrays
+    if (input.etdTimestamps !== undefined) shipment.etdTimestamps = input.etdTimestamps
+    if (input.etaTimestamps !== undefined) shipment.etaTimestamps = input.etaTimestamps
+    if (input.atdTimestamps !== undefined) shipment.atdTimestamps = input.atdTimestamps
+    if (input.ataTimestamps !== undefined) shipment.ataTimestamps = input.ataTimestamps
+
+    // Convenience: add single timestamp entries (e.g., manual overrides)
+    if (input.addEtdTimestamp) {
+      const entry = createTimestampEntry(
+        input.addEtdTimestamp.value,
+        input.addEtdTimestamp.offset ?? null,
+        input.addEtdTimestamp.source as TimestampSource,
+        input.addEtdTimestamp.sourceEventId,
+      )
+      shipment.etdTimestamps = addTimestampEntry(shipment.etdTimestamps, entry)
+    }
+    if (input.addEtaTimestamp) {
+      const entry = createTimestampEntry(
+        input.addEtaTimestamp.value,
+        input.addEtaTimestamp.offset ?? null,
+        input.addEtaTimestamp.source as TimestampSource,
+        input.addEtaTimestamp.sourceEventId,
+      )
+      shipment.etaTimestamps = addTimestampEntry(shipment.etaTimestamps, entry)
+    }
+    if (input.addAtdTimestamp) {
+      const entry = createTimestampEntry(
+        input.addAtdTimestamp.value,
+        input.addAtdTimestamp.offset ?? null,
+        input.addAtdTimestamp.source as TimestampSource,
+        input.addAtdTimestamp.sourceEventId,
+      )
+      shipment.atdTimestamps = addTimestampEntry(shipment.atdTimestamps, entry)
+    }
+    if (input.addAtaTimestamp) {
+      const entry = createTimestampEntry(
+        input.addAtaTimestamp.value,
+        input.addAtaTimestamp.offset ?? null,
+        input.addAtaTimestamp.source as TimestampSource,
+        input.addAtaTimestamp.sourceEventId,
+      )
+      shipment.ataTimestamps = addTimestampEntry(shipment.ataTimestamps, entry)
+    }
+
+    // Location data
+    if (input.originLocation !== undefined) shipment.originLocation = input.originLocation
+    if (input.destinationLocation !== undefined) shipment.destinationLocation = input.destinationLocation
+    if (input.vesselName !== undefined) shipment.vesselName = input.vesselName
+    if (input.vesselImo !== undefined) shipment.vesselImo = input.vesselImo
+    if (input.voyageNumber !== undefined) shipment.voyageNumber = input.voyageNumber
+    if (input.extra !== undefined) shipment.extra = input.extra
+
+    await em.flush()
+
+    await eventBus.emit('shipment_tracking.shipment.updated', {
+      id: shipment.id,
+      tenantId: shipment.tenantId,
+      organizationId: shipment.organizationId,
+    })
+
+    if (input.status && previousStatus !== input.status) {
+      await eventBus.emit('shipment_tracking.shipment.status_changed', {
+        id: shipment.id,
+        previousStatus,
+        newStatus: input.status,
+        tenantId: shipment.tenantId,
+        organizationId: shipment.organizationId,
+      })
+    }
+
+    return { id: shipment.id }
+  },
+}
+
+const deleteShipment: CommandHandler<{ id: string; tenantId: string; organizationId: string }, { id: string }> = {
+  id: 'shipment_tracking.shipment.delete',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const eventBus = ctx.container.resolve<EventBus>('eventBus')
+
+    // First verify the shipment exists and is not already deleted
+    const shipment = await em.findOne(Shipment, { id: input.id, deletedAt: null })
+    if (!shipment) throw new Error('Shipment not found')
+
+    const shipmentId = shipment.id
+    const tenantId = shipment.tenantId
+    const organizationId = shipment.organizationId
+
+    // Use nativeUpdate to avoid any MikroORM identity map issues
+    const now = new Date()
+    const affected = await em.nativeUpdate(
+      Shipment,
+      { id: shipmentId, deletedAt: null },
+      { deletedAt: now, updatedAt: now },
+    )
+
+    if (affected === 0) {
+      throw new Error('Shipment not found or already deleted')
+    }
+
+    await eventBus.emit('shipment_tracking.shipment.deleted', {
+      id: shipmentId,
+      tenantId,
+      organizationId,
+    })
+
+    return { id: shipmentId }
+  },
+}
+
+registerCommand(createShipment)
+registerCommand(updateShipment)
+registerCommand(deleteShipment)

package/src/modules/shipment_tracking/commands/shipsgo-configs.ts

@@ -0,0 +1,101 @@
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { ShipsGoConfig } from '../data/entities'
+import type { ShipsGoConfigUpsertInput } from '../data/validators'
+
+function ensureScope(ctx: CommandRuntimeContext, tenantId: string, organizationId: string) {
+  if (ctx.auth?.tenantId && ctx.auth.tenantId !== tenantId) {
+    throw new Error('Tenant mismatch')
+  }
+  if (!ctx.auth?.isSuperAdmin && ctx.auth?.organizationId && ctx.auth.organizationId !== organizationId) {
+    throw new Error('Organization mismatch')
+  }
+}
+
+/**
+ * Upsert the ShipsGo config — one row per organization/tenant. The api_token
+ * sentinel '__UNCHANGED__' leaves the stored (encrypted) token intact so the
+ * UI can round-trip without ever seeing the plaintext.
+ */
+const upsertShipsGoConfig: CommandHandler<ShipsGoConfigUpsertInput, { id: string }> = {
+  id: 'shipment_tracking.shipsgo_config.upsert',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    let config = await findOneWithDecryption(
+      em,
+      ShipsGoConfig,
+      { organizationId: input.organizationId, tenantId: input.tenantId },
+      {},
+      { tenantId: input.tenantId, organizationId: input.organizationId },
+    )
+
+    if (config) {
+      config.isEnabled = input.isEnabled
+      if (input.apiToken && input.apiToken !== '__UNCHANGED__') {
+        config.apiToken = input.apiToken
+      }
+      config.baseUrl = input.baseUrl ?? 'https://api.shipsgo.com/v2'
+      config.oceanEnabled = input.oceanEnabled
+      config.airEnabled = input.airEnabled
+      config.rateLimitRequests = input.rateLimitRequests
+      config.rateLimitWindowSeconds = input.rateLimitWindowSeconds
+      // Re-configuring after a soft delete revives the row.
+      config.isActive = true
+      config.deletedAt = null
+    } else {
+      config = em.create(ShipsGoConfig, {
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+        isEnabled: input.isEnabled,
+        apiToken: input.apiToken,
+        baseUrl: input.baseUrl ?? 'https://api.shipsgo.com/v2',
+        oceanEnabled: input.oceanEnabled,
+        airEnabled: input.airEnabled,
+        rateLimitRequests: input.rateLimitRequests,
+        rateLimitWindowSeconds: input.rateLimitWindowSeconds,
+      })
+    }
+
+    await em.flush()
+
+    return { id: config.id }
+  },
+}
+
+const deleteShipsGoConfig: CommandHandler<{ tenantId: string; organizationId: string }, { success: boolean }> = {
+  id: 'shipment_tracking.shipsgo_config.delete',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const config = await findOneWithDecryption(
+      em,
+      ShipsGoConfig,
+      { organizationId: input.organizationId, tenantId: input.tenantId },
+      {},
+      { tenantId: input.tenantId, organizationId: input.organizationId },
+    )
+
+    if (config) {
+      // Soft-delete: preserve the row (and its encrypted token) for audit, and
+      // stop it driving tracking. resolveConfig filters `deletedAt: null`, so a
+      // soft-deleted config falls back to the platform env account like no row.
+      config.isActive = false
+      config.deletedAt = new Date()
+      await em.flush()
+    }
+
+    return { success: true }
+  },
+}
+
+registerCommand(upsertShipsGoConfig)
+registerCommand(deleteShipsGoConfig)