@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/commands/tracking-jobs.ts

@@ -0,0 +1,158 @@
+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 { TrackingJob } from '../data/entities'
+import { generatePollSchedule, getNextPollDate } from '../lib/schedule-generator'
+import type { TrackingJobCreateInput } 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 createTrackingJob: CommandHandler<TrackingJobCreateInput, { id: string }> = {
+  id: 'shipment_tracking.tracking_job.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')
+
+    // Generate schedule if not provided
+    const schedule = input.schedule ?? generatePollSchedule({})
+    const nextPollAt = getNextPollDate(schedule)
+
+    const job = em.create(TrackingJob, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+      carrierCode: input.carrierCode,
+      referenceType: input.referenceType,
+      referenceValue: input.referenceValue,
+      originUnlocode: input.originUnlocode,
+      destinationUnlocode: input.destinationUnlocode,
+      status: 'active',
+      schedule,
+      nextPollAt,
+    })
+
+    await em.flush()
+
+    await eventBus.emit('shipment_tracking.tracking_job.created', {
+      id: job.id,
+      carrierCode: job.carrierCode,
+      referenceType: job.referenceType,
+      referenceValue: job.referenceValue,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+
+    return { id: job.id }
+  },
+}
+
+const pauseTrackingJob: CommandHandler<{ id: string; tenantId: string; organizationId: string }, { id: string }> = {
+  id: 'shipment_tracking.tracking_job.pause',
+
+  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')
+
+    const job = await em.findOne(TrackingJob, {
+      id: input.id,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+    if (!job) throw new Error('Tracking job not found')
+
+    job.status = 'paused'
+    await em.flush()
+
+    await eventBus.emit('shipment_tracking.tracking_job.updated', {
+      id: job.id,
+      status: 'paused',
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+
+    return { id: job.id }
+  },
+}
+
+const resumeTrackingJob: CommandHandler<{ id: string; tenantId: string; organizationId: string }, { id: string }> = {
+  id: 'shipment_tracking.tracking_job.resume',
+
+  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')
+
+    const job = await em.findOne(TrackingJob, {
+      id: input.id,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+    if (!job) throw new Error('Tracking job not found')
+
+    job.status = 'active'
+
+    // Recalculate next poll from schedule
+    if (job.schedule) {
+      job.nextPollAt = getNextPollDate(job.schedule)
+    }
+
+    await em.flush()
+
+    await eventBus.emit('shipment_tracking.tracking_job.updated', {
+      id: job.id,
+      status: 'active',
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+
+    return { id: job.id }
+  },
+}
+
+const deactivateTrackingJob: CommandHandler<{ id: string; tenantId: string; organizationId: string }, { id: string }> = {
+  id: 'shipment_tracking.tracking_job.deactivate',
+
+  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')
+
+    const job = await em.findOne(TrackingJob, {
+      id: input.id,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+    if (!job) throw new Error('Tracking job not found')
+
+    job.status = 'deactivated'
+    job.nextPollAt = null
+    await em.flush()
+
+    await eventBus.emit('shipment_tracking.tracking_job.completed', {
+      id: job.id,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    })
+
+    return { id: job.id }
+  },
+}
+
+registerCommand(createTrackingJob)
+registerCommand(pauseTrackingJob)
+registerCommand(resumeTrackingJob)
+registerCommand(deactivateTrackingJob)

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

@@ -0,0 +1,230 @@
+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 type { EventBus } from '@open-mercato/events'
+import type { TrackingService } from '../services/trackingService'
+import { Shipment } from '../data/entities'
+import { evaluatePreArrivalUpgrade } from '../lib/status-machine'
+import { getPrimaryTimestampValue } 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 (organizationId && !ctx.auth?.isSuperAdmin && ctx.auth?.organizationId && ctx.auth.organizationId !== organizationId) {
+    throw new Error('Organization mismatch')
+  }
+}
+
+type PollAllInput = {
+  tenantId: string
+  organizationId?: string
+}
+
+type PollAllResult = {
+  polled: number
+  newEvents: number
+  failed: number
+}
+
+/**
+ * Command to poll all active tracking jobs for a tenant/organization.
+ * This is called by the scheduler for daily re-polling.
+ */
+const pollAllActiveJobs: CommandHandler<PollAllInput, PollAllResult> = {
+  id: 'shipment_tracking.tracking.poll_all',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const trackingService = ctx.container.resolve<TrackingService>('shipmentTrackingService')
+
+    const result = await trackingService.pollAllActiveJobs(input.tenantId, input.organizationId)
+
+    console.log('[shipment-tracking:poll_all] Command completed:', {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      ...result,
+    })
+
+    return result
+  },
+
+  buildLog({ result, input }) {
+    return {
+      actionLabel: 'Poll all tracking jobs',
+      resourceKind: 'shipment_tracking.tracking',
+      resourceId: input.organizationId ?? input.tenantId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      details: {
+        polled: result.polled,
+        newEvents: result.newEvents,
+        failed: result.failed,
+      },
+    }
+  },
+}
+
+type PollSingleInput = {
+  jobId: string
+  tenantId: string
+  organizationId: string
+}
+
+type PollSingleResult = {
+  newEvents: number
+  shipmentsCreated: number
+  shipmentsUpdated: number
+}
+
+/**
+ * Command to poll a single tracking job.
+ * Can be called manually to trigger an immediate poll.
+ */
+const pollSingleJob: CommandHandler<PollSingleInput, PollSingleResult> = {
+  id: 'shipment_tracking.tracking.poll_single',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const trackingService = ctx.container.resolve<TrackingService>('shipmentTrackingService')
+
+    const result = await trackingService.pollTrackingJob(input.jobId)
+
+    return {
+      newEvents: result.newEvents,
+      shipmentsCreated: result.shipmentsCreated,
+      shipmentsUpdated: result.shipmentsUpdated,
+    }
+  },
+
+  buildLog({ result, input }) {
+    return {
+      actionLabel: 'Poll tracking job',
+      resourceKind: 'shipment_tracking.tracking_job',
+      resourceId: input.jobId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      details: {
+        newEvents: result.newEvents,
+        shipmentsCreated: result.shipmentsCreated,
+        shipmentsUpdated: result.shipmentsUpdated,
+      },
+    }
+  },
+}
+
+type EvaluatePreArrivalInput = {
+  tenantId: string
+  organizationId?: string
+}
+
+type EvaluatePreArrivalResult = {
+  evaluated: number
+  upgraded: number
+}
+
+/**
+ * Command to evaluate IN_TRANSIT shipments for PRE_ARRIVAL status upgrade.
+ * This is called by the scheduler to check shipments approaching their destination.
+ *
+ * A shipment is upgraded to PRE_ARRIVAL when:
+ * - Current status is IN_TRANSIT
+ * - ETA is within 7 days
+ * - No ATA (actual arrival) yet
+ */
+const evaluatePreArrival: CommandHandler<EvaluatePreArrivalInput, EvaluatePreArrivalResult> = {
+  id: 'shipment_tracking.tracking.evaluate_pre_arrival',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em')
+    const eventBus = ctx.container.resolve<EventBus>('eventBus')
+
+    // Find all IN_TRANSIT shipments for the tenant/organization
+    const filters: Record<string, unknown> = {
+      tenantId: input.tenantId,
+      status: 'IN_TRANSIT',
+      deletedAt: null,
+    }
+
+    if (input.organizationId) {
+      filters.organizationId = input.organizationId
+    }
+
+    const shipments = await em.find(Shipment, filters)
+
+    let upgraded = 0
+
+    for (const shipment of shipments) {
+      const eta = getPrimaryTimestampValue(shipment.etaTimestamps)
+      const ata = getPrimaryTimestampValue(shipment.ataTimestamps)
+
+      const newStatus = evaluatePreArrivalUpgrade(shipment.status, { eta, ata })
+
+      if (newStatus !== shipment.status) {
+        const previousStatus = shipment.status
+        shipment.status = newStatus
+
+        // Emit status_changed event
+        await eventBus.emit('shipment_tracking.shipment.status_changed', {
+          id: shipment.id,
+          previousStatus,
+          newStatus,
+          tenantId: shipment.tenantId,
+          organizationId: shipment.organizationId,
+        })
+
+        // Emit pre_arrival lifecycle event
+        await eventBus.emit('shipment_tracking.shipment.pre_arrival', {
+          id: shipment.id,
+          tenantId: shipment.tenantId,
+          organizationId: shipment.organizationId,
+        })
+
+        // Emit updated event
+        await eventBus.emit('shipment_tracking.shipment.updated', {
+          id: shipment.id,
+          tenantId: shipment.tenantId,
+          organizationId: shipment.organizationId,
+        })
+
+        upgraded++
+      }
+    }
+
+    await em.flush()
+
+    console.log('[shipment-tracking:evaluate_pre_arrival] Command completed:', {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      evaluated: shipments.length,
+      upgraded,
+    })
+
+    return {
+      evaluated: shipments.length,
+      upgraded,
+    }
+  },
+
+  buildLog({ result, input }) {
+    return {
+      actionLabel: 'Evaluate PRE_ARRIVAL status',
+      resourceKind: 'shipment_tracking.tracking',
+      resourceId: input.organizationId ?? input.tenantId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      details: {
+        evaluated: result.evaluated,
+        upgraded: result.upgraded,
+      },
+    }
+  },
+}
+
+registerCommand(pollAllActiveJobs)
+registerCommand(pollSingleJob)
+registerCommand(evaluatePreArrival)

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

@@ -0,0 +1,159 @@
+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, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { Webhook, WebhookDelivery } from '../data/entities'
+import type { WebhookCreateInput, WebhookUpdateInput } from '../data/validators'
+import { dispatchWebhook } from '../lib/webhook-dispatcher'
+
+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 createWebhook: CommandHandler<WebhookCreateInput, { id: string }> = {
+  id: 'shipment_tracking.webhook.create',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const webhook = em.create(Webhook, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+      url: input.url,
+      eventsSubscribed: input.eventsSubscribed,
+      hmacSecret: input.hmacSecret ?? null,
+      isActive: input.isActive ?? true,
+    })
+
+    await em.flush()
+
+    return { id: webhook.id }
+  },
+
+  async undo({ input, ctx }) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const webhooks = await findWithDecryption(em, Webhook, {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+    }, { orderBy: { createdAt: 'desc' }, limit: 1 })
+    const webhook = webhooks[0]
+    if (webhook) {
+      em.remove(webhook)
+      await em.flush()
+    }
+  },
+}
+
+const updateWebhook: CommandHandler<WebhookUpdateInput, { id: string }> = {
+  id: 'shipment_tracking.webhook.update',
+
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const webhook = await findOneWithDecryption(em, Webhook, { id: input.id })
+    if (!webhook) throw new Error('Webhook not found')
+
+    ensureScope(ctx, webhook.tenantId, webhook.organizationId)
+
+    if (input.url !== undefined) webhook.url = input.url
+    if (input.eventsSubscribed !== undefined) webhook.eventsSubscribed = input.eventsSubscribed
+    if (input.hmacSecret !== undefined) webhook.hmacSecret = input.hmacSecret
+    if (input.isActive !== undefined) webhook.isActive = input.isActive
+
+    await em.flush()
+
+    return { id: webhook.id }
+  },
+}
+
+const deleteWebhook: CommandHandler<{ id: string; tenantId: string; organizationId: string }, { id: string }> = {
+  id: 'shipment_tracking.webhook.delete',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const webhook = await findOneWithDecryption(em, Webhook, { id: input.id })
+    if (!webhook) throw new Error('Webhook not found')
+
+    em.remove(webhook)
+    await em.flush()
+
+    return { id: input.id }
+  },
+}
+
+const testWebhook: CommandHandler<
+  { id: string; tenantId: string; organizationId: string },
+  { success: boolean; deliveryId: string }
+> = {
+  id: 'shipment_tracking.webhook.test',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const webhook = await findOneWithDecryption(em, Webhook, { id: input.id })
+    if (!webhook) throw new Error('Webhook not found')
+
+    if (!webhook.isActive) {
+      throw new Error('Webhook is inactive')
+    }
+
+    // Build test payload
+    const testPayload = {
+      type: 'test',
+      event: 'webhook.test',
+      message: 'This is a test webhook delivery from Shipment Tracking',
+      timestamp: new Date().toISOString(),
+      webhookId: webhook.id,
+    }
+
+    // Create delivery record
+    // Use getReference to create a managed reference since webhook may be detached after decryption
+    const delivery = em.create(WebhookDelivery, {
+      webhook: em.getReference(Webhook, webhook.id),
+      eventType: 'webhook.test',
+      status: 'pending',
+      payload: testPayload,
+      retryCount: 0,
+    })
+
+    em.persist(delivery)
+    await em.flush()
+
+    // Dispatch synchronously for immediate feedback
+    const result = await dispatchWebhook({
+      url: webhook.url,
+      payload: testPayload,
+      hmacSecret: webhook.hmacSecret,
+    })
+
+    // Update delivery record with result
+    delivery.responseStatus = result.responseStatus ?? null
+    delivery.responseBody = result.responseBody ?? null
+    delivery.status = result.success ? 'success' : 'failed'
+    delivery.errorMessage = result.errorMessage ?? null
+    await em.flush()
+
+    if (!result.success) {
+      throw new Error(result.errorMessage || 'Webhook delivery failed')
+    }
+
+    return { success: true, deliveryId: delivery.id }
+  },
+}
+
+registerCommand(createWebhook)
+registerCommand(updateWebhook)
+registerCommand(deleteWebhook)
+registerCommand(testWebhook)