@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/backend/webhooks/page.tsx

@@ -0,0 +1,228 @@
+'use client'
+
+import * as React from 'react'
+import { useCallback, useMemo, useState } from 'react'
+import { Page, PageBody } from '@freighttech/ui/backend/Page'
+import { BooleanIcon } from '@freighttech/ui/backend/ValueIcons'
+import { Button } from '@freighttech/ui/primitives-v2'
+import {
+  DynamicTable,
+  TableSkeleton,
+  useDynamicTablePage,
+} from '@freighttech/ui/backend/dynamic-table'
+import type { ColumnDef, ContextMenuAction } from '@freighttech/ui/backend/dynamic-table'
+import { apiCallOrThrow } from '@freighttech/ui/backend/utils/apiCall'
+import { flash } from '@freighttech/ui/backend/FlashMessages'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Plus } from 'lucide-react'
+import { WebhookDrawer } from '../../components/WebhookDrawer'
+
+type WebhookRow = {
+  id: string
+  url: string
+  eventsSubscribed: string[]
+  isActive: boolean
+  createdAt: string | null
+}
+
+function mapItem(item: Record<string, unknown>): WebhookRow | null {
+  const id = typeof item.id === 'string' ? item.id : null
+  if (!id) return null
+
+  const eventsRaw = item.eventsSubscribed ?? item.events_subscribed
+  const eventsSubscribed = Array.isArray(eventsRaw) ? eventsRaw as string[] : []
+
+  return {
+    id,
+    url: (item.url as string) ?? '',
+    eventsSubscribed,
+    isActive: item.isActive === true || item.is_active === true,
+    createdAt: (item.createdAt as string) ?? (item.created_at as string) ?? null,
+  }
+}
+
+export default function WebhooksPage() {
+  const t = useT()
+  const [drawerOpen, setDrawerOpen] = useState(false)
+  const [drawerMode, setDrawerMode] = useState<'create' | 'edit'>('create')
+  const [selectedWebhookId, setSelectedWebhookId] = useState<string | undefined>(undefined)
+
+  const columns = useMemo<ColumnDef[]>(
+    () => [
+      {
+        data: 'url',
+        title: t('shipment_tracking.webhooks.fields.url', 'URL'),
+        width: 300,
+        readOnly: true,
+        renderer: (value: unknown) => (
+          <span className="font-medium text-sm truncate max-w-[280px] block">{String(value ?? '')}</span>
+        ),
+      },
+      {
+        data: 'eventsSubscribed',
+        title: t('shipment_tracking.webhooks.fields.eventsSubscribed', 'Subscribed Events'),
+        width: 300,
+        readOnly: true,
+        renderer: (value: unknown) => {
+          const events = Array.isArray(value) ? value : []
+          return <span className="text-sm">{events.join(', ') || '-'}</span>
+        },
+      },
+      {
+        data: 'isActive',
+        title: t('shipment_tracking.webhooks.fields.isActive', 'Active'),
+        width: 80,
+        readOnly: true,
+        renderer: (value: unknown) => <BooleanIcon value={value === true || value === 'true'} />,
+      },
+    ],
+    [t],
+  )
+
+  const handleRowClick = useCallback((_rowIndex: number, rowData: Record<string, unknown>) => {
+    const id = rowData?.id as string | undefined
+    if (id) {
+      setDrawerMode('edit')
+      setSelectedWebhookId(id)
+      setDrawerOpen(true)
+    }
+  }, [])
+
+  const createButton = useMemo(
+    () => (
+      <Button
+        variant="primary"
+        size="sm"
+        icon={<Plus className="h-4 w-4" />}
+        onClick={() => {
+          setDrawerMode('create')
+          setSelectedWebhookId(undefined)
+          setDrawerOpen(true)
+        }}
+      >
+        {t('shipment_tracking.webhooks.create', 'Create Webhook')}
+      </Button>
+    ),
+    [t],
+  )
+
+  const table = useDynamicTablePage<WebhookRow>({
+    source: '/api/shipment_tracking/webhooks',
+    // Saved views. Without this the perspective tab strip auto-hides
+    // (hidePerspectiveTabs ?? !hasPerspectives), so users cannot save or
+    // switch a view on this list at all.
+    perspectives: 'shipment_tracking_webhooks',
+    columns,
+    tableName: t('shipment_tracking.webhooks.title', 'Webhooks'),
+    defaultPageSize: 20,
+    mapApiItem: mapItem,
+    cellEdit: false,
+    tableProps: {
+      height: 'fill',
+      onRowClick: handleRowClick,
+      uiConfig: {
+        readOnlyStyle: 'normal',
+        hideAddRowButton: true,
+        searchBarEnd: createButton,
+      },
+    },
+  })
+
+  const handleDelete = useCallback(
+    async (id: string) => {
+      if (!confirm('Delete this webhook?')) return
+
+      try {
+        await apiCallOrThrow('/api/shipment_tracking/webhooks', {
+          method: 'DELETE',
+          body: JSON.stringify({ id }),
+        })
+        flash('Webhook deleted', 'success')
+        table.refresh()
+      } catch {
+        flash('Failed to delete webhook', 'error')
+      }
+    },
+    [table.refresh],
+  )
+
+  const handleTest = useCallback(
+    async (id: string) => {
+      try {
+        const { result } = await apiCallOrThrow<{ success: boolean; deliveryId: string }>(
+          '/api/shipment_tracking/webhooks/test',
+          {
+            method: 'POST',
+            body: JSON.stringify({ id }),
+          }
+        )
+        if (result?.success) {
+          flash(t('shipment_tracking.webhooks.flash.testSent', 'Test webhook sent successfully'), 'success')
+        } else {
+          flash(t('shipment_tracking.webhooks.flash.testFailed', 'Failed to send test webhook'), 'error')
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : t('shipment_tracking.webhooks.flash.testFailed', 'Failed to send test webhook')
+        flash(message, 'error')
+      }
+    },
+    [t],
+  )
+
+  const rowActions = useCallback(
+    (rowData: any): ContextMenuAction[] => {
+      if (!rowData?.id) return []
+      return [
+        { id: 'test', label: t('shipment_tracking.webhooks.actions.test', 'Test Webhook') },
+        { id: 'delete', label: 'Delete' },
+      ]
+    },
+    [t],
+  )
+
+  const handleRowAction = useCallback(
+    (actionId: string, rowData: any) => {
+      const id = rowData?.id as string | undefined
+      if (!id) return
+      if (actionId === 'test') handleTest(id)
+      else if (actionId === 'delete') handleDelete(id)
+    },
+    [handleTest, handleDelete],
+  )
+
+  if (table.isLoading) {
+    return (
+      <Page>
+        <PageBody>
+          <TableSkeleton rows={10} columns={3} />
+        </PageBody>
+      </Page>
+    )
+  }
+
+  return (
+    <Page>
+      <PageBody>
+        <div className="-mx-4 lg:-mx-6">
+          <DynamicTable
+            {...table.props}
+            striped
+            density="md"
+            rowActions={rowActions}
+            onRowAction={handleRowAction}
+          />
+        </div>
+
+        <WebhookDrawer
+          open={drawerOpen}
+          onOpenChange={setDrawerOpen}
+          mode={drawerMode}
+          webhookId={selectedWebhookId}
+          onSaved={() => {
+            table.refresh()
+          }}
+        />
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/shipment_tracking/ce.ts

@@ -0,0 +1,48 @@
+export const entities = [
+  {
+    id: 'shipment_tracking:shipment',
+    label: 'Shipment',
+    description: 'Ocean container shipment tracked across carriers.',
+    labelField: 'containerNumber',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'shipment_tracking:tracking_job',
+    label: 'Tracking Job',
+    description: 'Scheduled polling job for a shipment carrier.',
+    labelField: 'referenceValue',
+    showInSidebar: false,
+    defaultEditor: false,
+    fields: [],
+  },
+  {
+    id: 'shipment_tracking:cargo_event',
+    label: 'Cargo Event',
+    description: 'Individual tracking event for a shipment.',
+    labelField: 'eventCode',
+    showInSidebar: false,
+    defaultEditor: false,
+    fields: [],
+  },
+  {
+    id: 'shipment_tracking:carrier_config',
+    label: 'Carrier Config',
+    description: 'Carrier API configuration with authentication credentials.',
+    labelField: 'carrierCode',
+    showInSidebar: false,
+    defaultEditor: false,
+    fields: [],
+  },
+  {
+    id: 'shipment_tracking:webhook',
+    label: 'Webhook',
+    description: 'Webhook endpoint for shipment tracking event notifications.',
+    labelField: 'url',
+    showInSidebar: false,
+    defaultEditor: false,
+    fields: [],
+  },
+]
+
+export default entities

package/src/modules/shipment_tracking/cli.ts

@@ -0,0 +1,321 @@
+import type { ModuleCli } from '@open-mercato/shared/modules/registry'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { PoiNatsService } from './services/poiNatsService'
+
+// ─── Argument Parser ────────────────────────────────────────────
+
+function parseArgs(args: string[]): Record<string, string | boolean> {
+  const result: Record<string, string | boolean> = {}
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+
+      if (arg.includes('=')) {
+        const [k, v] = arg.slice(2).split('=')
+        result[k] = v
+      } else {
+        const nextArg = args[i + 1]
+        if (nextArg && !nextArg.startsWith('--')) {
+          result[key] = nextArg
+          i++
+        } else {
+          result[key] = true
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+// ─── Scheduler Service Type ─────────────────────────────────────
+
+type SchedulerServiceType = {
+  register: (registration: {
+    name: string
+    description?: string
+    scopeType: 'system' | 'organization' | 'tenant'
+    organizationId?: string
+    tenantId?: string
+    scheduleType: 'cron' | 'interval'
+    scheduleValue: string
+    timezone?: string
+    targetType: 'queue' | 'command'
+    targetQueue?: string
+    targetCommand?: string
+    targetPayload?: unknown
+    sourceType?: 'user' | 'module'
+    sourceModule?: string
+    isEnabled?: boolean
+  }) => Promise<void>
+}
+
+// ─── Setup Schedules Command ────────────────────────────────────
+
+/**
+ * Register scheduled jobs for shipment tracking
+ *
+ * This command registers the daily poll and pre-arrival evaluation schedules
+ * for an organization.
+ *
+ * Usage:
+ *   yarn mercato shipment_tracking setup-schedules --tenant <tenantId> --org <organizationId>
+ *
+ * After running, start the scheduler to sync with BullMQ:
+ *   yarn mercato scheduler start
+ */
+const setupSchedulesCommand: ModuleCli = {
+  command: 'setup-schedules',
+  async run(rest) {
+    const args = parseArgs(rest)
+    const tenantId = String(args.tenantId ?? args.tenant ?? '')
+    const organizationId = String(args.organizationId ?? args.orgId ?? args.org ?? '')
+
+    if (!tenantId || !organizationId) {
+      console.error(
+        'Usage: mercato shipment_tracking setup-schedules --tenant <tenantId> --org <organizationId>',
+      )
+      console.error('')
+      console.error('This command registers the scheduled jobs for shipment tracking:')
+      console.error('  - Daily poll schedule (6:00 AM UTC): polls all active tracking jobs')
+      console.error('  - Pre-arrival evaluation (every 6h): upgrades IN_TRANSIT → PRE_ARRIVAL')
+      console.error('')
+      console.error('After running, sync with BullMQ:')
+      console.error('  yarn mercato scheduler start')
+      return
+    }
+
+    const { resolve } = await createRequestContainer()
+
+    try {
+      const schedulerService = resolve<SchedulerServiceType>('schedulerService')
+
+      if (!schedulerService) {
+        console.error('❌ Scheduler service not available.')
+        console.error('   Make sure the scheduler module is installed and configured.')
+        process.exit(1)
+      }
+
+      console.log('📅 Registering shipment tracking schedules...\n')
+
+      // Register daily poll schedule
+      await schedulerService.register({
+        name: 'Daily Shipment Tracking Poll',
+        description:
+          'Polls all active tracking jobs for carrier updates every day at 6:00 AM UTC.',
+        scopeType: 'organization',
+        tenantId,
+        organizationId,
+        scheduleType: 'cron',
+        scheduleValue: '0 6 * * *', // 6:00 AM UTC daily
+        timezone: 'UTC',
+        targetType: 'command',
+        targetCommand: 'shipment_tracking.tracking.poll_all',
+        targetPayload: {
+          tenantId,
+          organizationId,
+        },
+        sourceType: 'module',
+        sourceModule: 'shipment_tracking',
+        isEnabled: true,
+      })
+      console.log(`  ✅ Registered daily poll schedule`)
+      console.log(`     Cron: 0 6 * * * (6:00 AM UTC daily)`)
+
+      // Register PRE_ARRIVAL evaluation schedule
+      await schedulerService.register({
+        name: 'Pre-Arrival Status Evaluation',
+        description:
+          'Checks IN_TRANSIT shipments every 6 hours and upgrades them to PRE_ARRIVAL when ETA is within 7 days.',
+        scopeType: 'organization',
+        tenantId,
+        organizationId,
+        scheduleType: 'cron',
+        scheduleValue: '0 */6 * * *', // Every 6 hours
+        timezone: 'UTC',
+        targetType: 'command',
+        targetCommand: 'shipment_tracking.tracking.evaluate_pre_arrival',
+        targetPayload: {
+          tenantId,
+          organizationId,
+        },
+        sourceType: 'module',
+        sourceModule: 'shipment_tracking',
+        isEnabled: true,
+      })
+      console.log(`  ✅ Registered pre-arrival evaluation schedule`)
+      console.log(`     Cron: 0 */6 * * * (every 6 hours)`)
+
+      console.log('')
+      console.log('✅ Schedules registered successfully!')
+      console.log('')
+      console.log('Next steps:')
+      console.log('  1. Sync schedules with BullMQ: yarn mercato scheduler start')
+      console.log('  2. Ensure worker is running: yarn mercato worker:start')
+      console.log('')
+    } catch (error: any) {
+      if (error.message?.includes('not registered')) {
+        console.error('❌ Scheduler service not available.')
+        console.error('   Make sure the scheduler module is installed.')
+      } else {
+        console.error('❌ Failed to register schedules:', error.message)
+      }
+      process.exit(1)
+    }
+  },
+}
+
+// ─── POI NATS Subscriber Commands ────────────────────────────
+
+/**
+ * POI NATS Worker
+ *
+ * Long-running worker process that consumes POI proximity events from NATS JetStream.
+ * Run this as a separate process/service alongside the main app.
+ *
+ * Usage:
+ *   yarn mercato shipment_tracking poi:worker
+ *
+ * With pm2:
+ *   pm2 start "yarn mercato shipment_tracking poi:worker" --name poi-worker
+ *
+ * With systemd:
+ *   ExecStart=/path/to/yarn mercato shipment_tracking poi:worker
+ */
+const poiWorkerCommand: ModuleCli = {
+  command: 'poi:worker',
+  async run() {
+    const { resolve } = await createRequestContainer()
+
+    try {
+      const poiService = resolve<PoiNatsService>('poiNatsService')
+
+      if (!poiService) {
+        console.error('[poi-worker] PoiNatsService not available')
+        process.exit(1)
+      }
+
+      // Check if POI NATS is configured
+      if (!poiService.isConfigured()) {
+        console.log('[poi-worker] POI_NATS_URL not configured, exiting')
+        console.log('[poi-worker] Set POI_NATS_URL environment variable to enable')
+        process.exit(0)
+      }
+
+      console.log('[poi-worker] Starting POI NATS consumer...')
+
+      // Start the NATS subscriber
+      await poiService.start()
+
+      const stats = poiService.getStats()
+      console.log(`[poi-worker] Consumer started at ${stats.connectedAt?.toISOString()}`)
+      console.log('[poi-worker] Listening for POI proximity events')
+
+      // Keep the process alive and handle graceful shutdown
+      let isShuttingDown = false
+      const gracefulShutdown = async () => {
+        if (isShuttingDown) return
+        isShuttingDown = true
+        console.log('[poi-worker] Shutting down...')
+        try {
+          await poiService.stop()
+          console.log('[poi-worker] Stopped')
+        } catch (error) {
+          console.error('[poi-worker] Error during shutdown:', error)
+        }
+        process.exit(0)
+      }
+
+      process.on('SIGINT', gracefulShutdown)
+      process.on('SIGTERM', gracefulShutdown)
+
+      // Keep alive
+      await new Promise(() => {})
+    } catch (error: any) {
+      console.error('[poi-worker] Failed to start:', error.message)
+      process.exit(1)
+    }
+  },
+}
+
+const poiStatusCommand: ModuleCli = {
+  command: 'poi:status',
+  async run() {
+    const { resolve } = await createRequestContainer()
+
+    try {
+      const poiService = resolve<PoiNatsService>('poiNatsService')
+
+      if (!poiService) {
+        console.error('PoiNatsService not available.')
+        process.exit(1)
+      }
+
+      console.log('POI NATS Subscriber Status\n')
+
+      // Check if POI NATS is configured
+      if (!poiService.isConfigured()) {
+        console.log('  Status:             not configured')
+        console.log('')
+        console.log('Set POI_NATS_URL environment variable to enable POI event subscription.')
+        process.exit(0)
+      }
+
+      const stats = poiService.getStats()
+
+      console.log(`  Status:             ${stats.status}`)
+      console.log(`  Connected at:       ${stats.connectedAt?.toISOString() ?? 'N/A'}`)
+      console.log(`  Messages received:  ${stats.messagesReceived}`)
+      console.log(`  Messages processed: ${stats.messagesProcessed}`)
+      console.log(`  Events created:     ${stats.eventsCreated}`)
+      console.log(`  Errors:             ${stats.errors}`)
+      console.log(`  Last message at:    ${stats.lastMessageAt?.toISOString() ?? 'N/A'}`)
+      console.log('')
+    } catch (error: any) {
+      console.error('Failed to get status:', error.message)
+      process.exit(1)
+    }
+  },
+}
+
+const poiHelpCommand: ModuleCli = {
+  command: 'poi:help',
+  async run() {
+    console.log('POI NATS Consumer Commands\n')
+    console.log('Commands:')
+    console.log('  poi:worker  Start the POI NATS consumer worker (long-running)')
+    console.log('  poi:status  Show consumer status and statistics')
+    console.log('  poi:help    Show this help message')
+    console.log('')
+    console.log('Environment Variables:')
+    console.log('  POI_NATS_URL      NATS server URL (required to enable)')
+    console.log('  POI_NATS_STREAM   JetStream stream name (default: AIS_STREAM)')
+    console.log('  POI_NATS_SUBJECT  Subject filter (default: ais.ship.proximity.events)')
+    console.log('  POI_NATS_CONSUMER Durable consumer name (default: shipment-tracking-poi)')
+    console.log('')
+    console.log('Prerequisites:')
+    console.log('  Create a durable consumer on the NATS server:')
+    console.log('    nats consumer add AIS_STREAM shipment-tracking-poi \\')
+    console.log('      --filter "ais.ship.proximity.events" \\')
+    console.log('      --ack explicit --deliver all --replay instant')
+    console.log('')
+    console.log('Running as a service:')
+    console.log('  # Direct:')
+    console.log('  POI_NATS_URL=nats://localhost:4222 yarn mercato shipment_tracking poi:worker')
+    console.log('')
+    console.log('  # With pm2:')
+    console.log('  pm2 start "yarn mercato shipment_tracking poi:worker" --name poi-worker')
+    console.log('')
+    console.log('  # With Docker (add to docker-compose.yml):')
+    console.log('  poi-worker:')
+    console.log('    command: yarn mercato shipment_tracking poi:worker')
+    console.log('    environment:')
+    console.log('      - POI_NATS_URL=nats://nats:4222')
+    console.log('')
+  },
+}
+
+export default [setupSchedulesCommand, poiWorkerCommand, poiStatusCommand, poiHelpCommand]

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

@@ -0,0 +1,94 @@
+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 { BicConfig } from '../data/entities'
+import type { BicConfigUpsertInput } 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 BIC config - creates if not exists, updates if exists.
+ * There is only one BIC config per organization/tenant.
+ */
+const upsertBicConfig: CommandHandler<BicConfigUpsertInput, { id: string }> = {
+  id: 'shipment_tracking.bic_config.upsert',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    // Find existing config for this org/tenant
+    let bicConfig = await findOneWithDecryption(
+      em,
+      BicConfig,
+      { organizationId: input.organizationId, tenantId: input.tenantId },
+      {},
+      { tenantId: input.tenantId, organizationId: input.organizationId },
+    )
+
+    if (bicConfig) {
+      // Update existing
+      bicConfig.isEnabled = input.isEnabled
+      bicConfig.username = input.username
+      // Only update password if a new one was provided (not the sentinel value)
+      if (input.password && input.password !== '__UNCHANGED__') {
+        bicConfig.password = input.password
+      }
+      bicConfig.baseUrl = input.baseUrl ?? 'https://api.bic-code.org'
+    } else {
+      // Create new
+      bicConfig = em.create(BicConfig, {
+        organizationId: input.organizationId,
+        tenantId: input.tenantId,
+        isEnabled: input.isEnabled,
+        username: input.username,
+        password: input.password,
+        baseUrl: input.baseUrl ?? 'https://api.bic-code.org',
+      })
+    }
+
+    await em.flush()
+
+    return { id: bicConfig.id }
+  },
+}
+
+/**
+ * Delete BIC config
+ */
+const deleteBicConfig: CommandHandler<{ tenantId: string; organizationId: string }, { success: boolean }> = {
+  id: 'shipment_tracking.bic_config.delete',
+
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    const bicConfig = await findOneWithDecryption(
+      em,
+      BicConfig,
+      { organizationId: input.organizationId, tenantId: input.tenantId },
+      {},
+      { tenantId: input.tenantId, organizationId: input.organizationId },
+    )
+
+    if (bicConfig) {
+      em.remove(bicConfig)
+      await em.flush()
+    }
+
+    return { success: true }
+  },
+}
+
+registerCommand(upsertBicConfig)
+registerCommand(deleteBicConfig)