@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/backend/terminal-containers/page.meta.ts

@@ -0,0 +1,16 @@
+import React from 'react'
+import { Container } from 'lucide-react'
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['terminal_tracking.tracking_jobs.view'],
+  pageTitle: 'Tracked Containers',
+  pageTitleKey: 'terminal_tracking.nav.tracking_jobs',
+  pageGroup: 'Terminal Tracking',
+  pageGroupKey: 'terminal_tracking.nav.group',
+  pageContext: 'settings' as const,
+  pagePriority: 10,
+  pageOrder: 110,
+  icon: React.createElement(Container, { size: 16 }),
+  breadcrumb: [{ label: 'Tracked Containers', labelKey: 'terminal_tracking.nav.tracking_jobs' }],
+}

package/src/modules/terminal_tracking/backend/terminal-containers/page.tsx

@@ -0,0 +1,328 @@
+'use client'
+
+import * as React from 'react'
+import { useCallback, useMemo, useState } from 'react'
+import { Page, PageBody } from '@freighttech/ui/backend/Page'
+import { DynamicTable, TableSkeleton, useDynamicTablePage } from '@freighttech/ui/backend/dynamic-table'
+import type { ColumnDef } from '@freighttech/ui/backend/dynamic-table'
+import { RowActions, type RowActionItem } from '@freighttech/ui/backend/RowActions'
+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 {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogFooter,
+} from '@freighttech/ui/primitives/dialog'
+import { Button } from '@freighttech/ui/primitives/button'
+import { Input } from '@freighttech/ui/primitives/input'
+import { Label } from '@freighttech/ui/primitives/label'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@freighttech/ui/primitives/card'
+import { Loader2 } from 'lucide-react'
+import { ContainerDetailsDrawer } from '../../components/ContainerDetailsDrawer'
+
+type JobRow = {
+  id: string
+  terminalCode: string
+  containerNumber: string
+  status: string
+  gateInAt: string | null
+  gateOutAt: string | null
+  holds: string[]
+  lastPollAt: string | null
+}
+
+function mapItem(item: Record<string, unknown>): JobRow | null {
+  const id = typeof item.id === 'string' ? item.id : null
+  if (!id) return null
+  return {
+    id,
+    terminalCode: (item.terminalCode as string) ?? '',
+    containerNumber: (item.containerNumber as string) ?? '',
+    status: (item.status as string) ?? '',
+    gateInAt: (item.gateInAt as string) ?? null,
+    gateOutAt: (item.gateOutAt as string) ?? null,
+    holds: Array.isArray(item.holds) ? (item.holds as string[]) : [],
+    lastPollAt: (item.lastPollAt as string) ?? null,
+  }
+}
+
+function DateTimeCell({ value }: { value: unknown }): React.ReactElement {
+  return <span className="text-sm">{value ? new Date(String(value)).toLocaleString() : '-'}</span>
+}
+
+const API = '/api/terminal_tracking/tracking-jobs'
+
+export default function TrackingJobsPage() {
+  const t = useT()
+  const [dialogOpen, setDialogOpen] = useState(false)
+  const [terminalCode, setTerminalCode] = useState('')
+  const [containerNumber, setContainerNumber] = useState('')
+  const [submitting, setSubmitting] = useState(false)
+
+  const columns = useMemo<ColumnDef[]>(
+    () => [
+      {
+        data: 'containerNumber',
+        title: t('terminal_tracking.tracking_job.containerNumber', 'Container'),
+        width: 160,
+        readOnly: true,
+        renderer: (v: unknown) => <span className="font-medium font-mono">{String(v ?? '')}</span>,
+      },
+      {
+        data: 'terminalCode',
+        title: t('terminal_tracking.terminal_config.terminalCode', 'Terminal'),
+        width: 120,
+        readOnly: true,
+      },
+      {
+        data: 'status',
+        title: t('terminal_tracking.tracking_job.status', 'Status'),
+        width: 110,
+        readOnly: true,
+      },
+      {
+        data: 'gateInAt',
+        title: t('terminal_tracking.tracking_job.gateIn', 'Gate in'),
+        width: 170,
+        readOnly: true,
+        renderer: (v: unknown) => <DateTimeCell value={v} />,
+      },
+      {
+        data: 'gateOutAt',
+        title: t('terminal_tracking.tracking_job.gateOut', 'Gate out'),
+        width: 170,
+        readOnly: true,
+        renderer: (v: unknown) => <DateTimeCell value={v} />,
+      },
+      {
+        data: 'holds',
+        title: t('terminal_tracking.tracking_job.holds', 'Holds'),
+        width: 220,
+        readOnly: true,
+        renderer: (v: unknown) => {
+          const holds = Array.isArray(v) ? (v as string[]) : []
+          if (!holds.length) return <span className="text-sm text-muted-foreground">-</span>
+          return (
+            <span className="text-sm" title={holds.join(', ')}>
+              {holds.join(', ')}
+            </span>
+          )
+        },
+      },
+      {
+        data: 'lastPollAt',
+        title: t('terminal_tracking.tracking_job.lastPollAt', 'Last polled'),
+        width: 180,
+        readOnly: true,
+        renderer: (v: unknown) => <DateTimeCell value={v} />,
+      },
+    ],
+    [t],
+  )
+
+  const openCreate = useCallback(() => {
+    setTerminalCode('')
+    setContainerNumber('')
+    setDialogOpen(true)
+  }, [])
+
+  const addButton = useMemo(
+    () => (
+      <Button size="sm" onClick={openCreate}>
+        {t('terminal_tracking.tracking_job.create', 'Track Container')}
+      </Button>
+    ),
+    [openCreate, t],
+  )
+
+  const table = useDynamicTablePage<JobRow>({
+    source: API,
+    columns,
+    tableName: t('terminal_tracking.tracking_job.title', 'Tracked Containers'),
+    defaultPageSize: 20,
+    mapApiItem: mapItem,
+    cellEdit: false,
+    tableProps: {
+      uiConfig: {
+        readOnlyStyle: 'normal',
+        hideAddRowButton: true,
+        topBarEnd: addButton,
+      },
+    },
+  })
+
+  // Grow the grid to fit its rows so the page — not the table — owns the scroll.
+  // `height` sizes the WHOLE DynamicTable (toolbar + scroll area + pagination as a
+  // flex column), so it must cover the chrome (~100px) plus the scroll area's own
+  // content: a 37px column header + one 37px row each. Sizing to content this way
+  // removes the inner scrollbar; a small row floor keeps the empty state sensible.
+  const CHROME_PX = 100 // top toolbar + bottom pagination
+  const ROW_PX = 37 // matches the DynamicTable virtualizer row estimate
+  const rowCount = table.props.data?.length ?? 0
+  const tableHeight = `${CHROME_PX + ROW_PX + Math.max(rowCount, 3) * ROW_PX}px`
+
+  const handleSubmit = useCallback(async () => {
+    if (submitting) return
+    if (!terminalCode.trim() || !containerNumber.trim()) {
+      flash(t('terminal_tracking.tracking_job.validation.required', 'Terminal code and container number are required'), 'error')
+      return
+    }
+    setSubmitting(true)
+    try {
+      await apiCallOrThrow(API, {
+        method: 'POST',
+        body: JSON.stringify({ terminalCode: terminalCode.trim(), containerNumber: containerNumber.trim() }),
+      })
+      flash(t('terminal_tracking.tracking_job.flash.created', 'Container is now tracked'), 'success')
+      setDialogOpen(false)
+      table.refresh()
+    } catch (err) {
+      flash(err instanceof Error ? err.message : 'Failed to track container', 'error')
+    } finally {
+      setSubmitting(false)
+    }
+  }, [submitting, terminalCode, containerNumber, table, t])
+
+  const handlePoll = useCallback(
+    async (id: string) => {
+      try {
+        const { result } = await apiCallOrThrow<{ newEvents: number; updatedEvents?: number }>(`${API}/poll`, {
+          method: 'POST',
+          body: JSON.stringify({ id }),
+        })
+        flash(
+          t('terminal_tracking.tracking_job.flash.polled', 'Polled — {n} new, {u} updated event(s)')
+            .replace('{n}', String(result?.newEvents ?? 0))
+            .replace('{u}', String(result?.updatedEvents ?? 0)),
+          'success',
+        )
+        table.refresh()
+      } catch (err) {
+        flash(err instanceof Error ? err.message : 'Poll failed', 'error')
+      }
+    },
+    [table, t],
+  )
+
+  const handleDelete = useCallback(
+    async (id: string) => {
+      if (!confirm(t('terminal_tracking.tracking_job.confirmDelete', 'Stop tracking this container?'))) return
+      try {
+        await apiCallOrThrow(API, { method: 'DELETE', body: JSON.stringify({ id }) })
+        flash(t('terminal_tracking.tracking_job.flash.deleted', 'Tracking stopped'), 'success')
+        table.refresh()
+      } catch (err) {
+        flash(err instanceof Error ? err.message : 'Failed to stop tracking', 'error')
+      }
+    },
+    [table, t],
+  )
+
+  const handleDialogKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+        event.preventDefault()
+        handleSubmit()
+      }
+    },
+    [handleSubmit],
+  )
+
+  const [selectedJobId, setSelectedJobId] = useState<string | null>(null)
+  const [drawerOpen, setDrawerOpen] = useState(false)
+
+  const openDetails = useCallback((id: string) => {
+    setSelectedJobId(id)
+    setDrawerOpen(true)
+  }, [])
+
+  const handleRowClick = useCallback(
+    (_rowIndex: number, rowData: Record<string, unknown>) => {
+      const id = rowData?.id as string | undefined
+      if (id) openDetails(id)
+    },
+    [openDetails],
+  )
+
+  const actionsRenderer = useCallback(
+    (rowData: { id: string }) => {
+      if (!rowData?.id) return null
+      const items: RowActionItem[] = [
+        { label: t('terminal_tracking.tracking_job.actions.details', 'Details'), onSelect: () => openDetails(rowData.id) },
+        { label: t('terminal_tracking.tracking_job.actions.poll', 'Poll now'), onSelect: () => handlePoll(rowData.id) },
+        { label: t('common.delete', 'Delete'), onSelect: () => handleDelete(rowData.id), destructive: true },
+      ]
+      return <RowActions items={items} />
+    },
+    [t, openDetails, handlePoll, handleDelete],
+  )
+
+  if (table.isLoading) {
+    return (
+      <Page>
+        <PageBody className="space-y-6">
+          <Card>
+            <CardHeader>
+              <CardTitle>{t('terminal_tracking.tracking_job.title', 'Tracked Containers')}</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <TableSkeleton rows={5} columns={7} />
+            </CardContent>
+          </Card>
+        </PageBody>
+      </Page>
+    )
+  }
+
+  return (
+    <Page>
+      <PageBody className="space-y-6">
+        <Card>
+          <CardHeader>
+            <CardTitle>{t('terminal_tracking.tracking_job.title', 'Tracked Containers')}</CardTitle>
+            <CardDescription>
+              {t('terminal_tracking.tracking_job.description', 'Containers polled at configured terminals. Use "Poll now" to fetch immediately.')}
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <DynamicTable {...table.props} height={tableHeight} actionsRenderer={actionsRenderer} onRowClick={handleRowClick} />
+          </CardContent>
+        </Card>
+
+        <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>
+          <DialogContent className="sm:max-w-md" onKeyDown={handleDialogKeyDown}>
+            <DialogHeader>
+              <DialogTitle>{t('terminal_tracking.tracking_job.create', 'Track Container')}</DialogTitle>
+            </DialogHeader>
+            <div className="grid gap-4 py-2">
+              <div className="grid gap-2">
+                <Label htmlFor="terminalCode">{t('terminal_tracking.terminal_config.terminalCode', 'Terminal code')}</Label>
+                <Input id="terminalCode" value={terminalCode} autoFocus
+                  onChange={(e) => setTerminalCode(e.target.value)} placeholder="bct" />
+              </div>
+              <div className="grid gap-2">
+                <Label htmlFor="containerNumber">{t('terminal_tracking.tracking_job.containerNumber', 'Container')}</Label>
+                <Input id="containerNumber" value={containerNumber}
+                  onChange={(e) => setContainerNumber(e.target.value.toUpperCase())} placeholder="GCXU5598460" className="font-mono" />
+              </div>
+            </div>
+            <DialogFooter>
+              <Button variant="outline" onClick={() => setDialogOpen(false)} disabled={submitting}>
+                {t('common.cancel', 'Cancel')}
+              </Button>
+              <Button onClick={handleSubmit} disabled={submitting}>
+                {submitting ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
+                {t('common.create', 'Create')}
+              </Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+
+        <ContainerDetailsDrawer open={drawerOpen} onOpenChange={setDrawerOpen} jobId={selectedJobId} />
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/terminal_tracking/ce.ts

@@ -0,0 +1,31 @@
+export const entities = [
+  {
+    id: 'terminal_tracking:terminal_config',
+    label: 'Terminal Config',
+    description: 'Container terminal API configuration with credentials and matching identifiers.',
+    labelField: 'displayName',
+    showInSidebar: false,
+    defaultEditor: false,
+    fields: [],
+  },
+  {
+    id: 'terminal_tracking:tracking_job',
+    label: 'Terminal Tracking Job',
+    description: 'A container tracked at a terminal.',
+    labelField: 'containerNumber',
+    showInSidebar: false,
+    defaultEditor: false,
+    fields: [],
+  },
+  {
+    id: 'terminal_tracking:terminal_event',
+    label: 'Terminal Event',
+    description: 'A normalized terminal event for a container.',
+    labelField: 'eventCode',
+    showInSidebar: false,
+    defaultEditor: false,
+    fields: [],
+  },
+]
+
+export default entities

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

@@ -0,0 +1,3 @@
+import './terminal-configs'
+import './tracking-jobs'
+import './terminal-tracking'

package/src/modules/terminal_tracking/commands/terminal-configs.ts

@@ -0,0 +1,132 @@
+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 { TerminalConfig } from '../data/entities'
+import type { TerminalTrackingService } from '../services/terminalTrackingService'
+import type { TerminalRegistry } from '../services/terminalRegistry'
+import { ensureTerminalPollSchedule } from '../lib/ensure-schedule'
+import type {
+  TerminalConfigCreateInput,
+  TerminalConfigUpdateInput,
+  TerminalConfigDeleteInput,
+  TerminalConfigTestInput,
+} 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 createTerminalConfig: CommandHandler<TerminalConfigCreateInput, { id: string }> = {
+  id: 'terminal_tracking.terminal_config.create',
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+
+    // Endpoint paths are standardized per adapter family; default from the
+    // adapter when the client omits them (only non-standard terminals override).
+    const registry = ctx.container.resolve<TerminalRegistry>('terminalTrackingRegistry')
+    const endpoints = input.endpoints ?? registry.get(input.adapterType)?.defaultEndpoints
+    if (!endpoints) {
+      throw new Error(`Unknown adapter type '${input.adapterType}' and no endpoints provided`)
+    }
+
+    const config = em.create(TerminalConfig, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+      terminalCode: input.terminalCode,
+      adapterType: input.adapterType,
+      displayName: input.displayName,
+      baseUrl: input.baseUrl,
+      proxyUrl: input.proxyUrl ?? null,
+      endpoints,
+      authType: input.authType,
+      tokenUrl: input.tokenUrl ?? null,
+      scope: input.scope ?? null,
+      clientId: input.clientId ?? null,
+      authConfig: input.authConfig ?? null,
+      rateLimitRequests: input.rateLimitRequests ?? 200,
+      rateLimitWindowSeconds: input.rateLimitWindowSeconds ?? 60,
+      unlocode: input.unlocode ?? null,
+      bicCodes: input.bicCodes ?? null,
+      smdgCodes: input.smdgCodes ?? null,
+      nameAliases: input.nameAliases ?? null,
+      isActive: input.isActive ?? true,
+    })
+    await em.flush()
+    // Self-heal the periodic poll schedule for orgs that predate the module.
+    await ensureTerminalPollSchedule(ctx.container, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+    })
+    return { id: config.id }
+  },
+}
+
+const updateTerminalConfig: CommandHandler<TerminalConfigUpdateInput, { id: string }> = {
+  id: 'terminal_tracking.terminal_config.update',
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const config = await findOneWithDecryption(em, TerminalConfig, { id: input.id, deletedAt: null })
+    if (!config) throw new Error('Terminal config not found')
+    ensureScope(ctx, config.tenantId, config.organizationId)
+
+    if (input.adapterType !== undefined) config.adapterType = input.adapterType
+    if (input.displayName !== undefined) config.displayName = input.displayName
+    if (input.baseUrl !== undefined) config.baseUrl = input.baseUrl
+    if (input.proxyUrl !== undefined) config.proxyUrl = input.proxyUrl ?? null
+    if (input.endpoints !== undefined) config.endpoints = input.endpoints
+    if (input.authType !== undefined) config.authType = input.authType
+    if (input.tokenUrl !== undefined) config.tokenUrl = input.tokenUrl ?? null
+    if (input.scope !== undefined) config.scope = input.scope ?? null
+    if (input.clientId !== undefined) config.clientId = input.clientId ?? null
+    if (input.authConfig !== undefined) config.authConfig = input.authConfig ?? null
+    if (input.rateLimitRequests !== undefined) config.rateLimitRequests = input.rateLimitRequests
+    if (input.rateLimitWindowSeconds !== undefined) config.rateLimitWindowSeconds = input.rateLimitWindowSeconds
+    if (input.unlocode !== undefined) config.unlocode = input.unlocode ?? null
+    if (input.bicCodes !== undefined) config.bicCodes = input.bicCodes ?? null
+    if (input.smdgCodes !== undefined) config.smdgCodes = input.smdgCodes ?? null
+    if (input.nameAliases !== undefined) config.nameAliases = input.nameAliases ?? null
+    if (input.isActive !== undefined) config.isActive = input.isActive
+
+    await em.flush()
+    await ensureTerminalPollSchedule(ctx.container, {
+      organizationId: config.organizationId,
+      tenantId: config.tenantId,
+    })
+    return { id: config.id }
+  },
+}
+
+const deleteTerminalConfig: CommandHandler<TerminalConfigDeleteInput, { id: string }> = {
+  id: 'terminal_tracking.terminal_config.delete',
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const config = await findOneWithDecryption(em, TerminalConfig, { id: input.id, deletedAt: null })
+    if (!config) throw new Error('Terminal config not found')
+    ensureScope(ctx, config.tenantId, config.organizationId)
+    config.deletedAt = new Date()
+    await em.flush()
+    return { id: config.id }
+  },
+}
+
+const testTerminalConfig: CommandHandler<
+  TerminalConfigTestInput,
+  { success: boolean; message: string; latencyMs?: number }
+> = {
+  id: 'terminal_tracking.terminal_config.test',
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+    const service = ctx.container.resolve<TerminalTrackingService>('terminalTrackingService')
+    return service.testTerminalConfig(input)
+  },
+}
+
+registerCommand(createTerminalConfig)
+registerCommand(updateTerminalConfig)
+registerCommand(deleteTerminalConfig)
+registerCommand(testTerminalConfig)

package/src/modules/terminal_tracking/commands/terminal-tracking.ts

@@ -0,0 +1,34 @@
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import type { TerminalTrackingService } from '../services/terminalTrackingService'
+
+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 }
+
+const pollAllActiveJobs: CommandHandler<PollAllInput, PollAllResult> = {
+  id: 'terminal_tracking.tracking.poll_all',
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+    const service = ctx.container.resolve<TerminalTrackingService>('terminalTrackingService')
+    return service.pollAllActiveJobs(input.tenantId, input.organizationId)
+  },
+  buildLog({ result, input }) {
+    return {
+      actionLabel: 'Poll all terminal tracking jobs',
+      resourceKind: 'terminal_tracking.tracking',
+      resourceId: input.organizationId ?? input.tenantId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      details: { polled: result.polled, newEvents: result.newEvents, failed: result.failed },
+    }
+  },
+}
+
+registerCommand(pollAllActiveJobs)

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

@@ -0,0 +1,69 @@
+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 { TerminalTrackingJob } from '../data/entities'
+import type { TerminalTrackingService } from '../services/terminalTrackingService'
+import { ensureTerminalPollSchedule } from '../lib/ensure-schedule'
+import type {
+  TrackingJobCreateInput,
+  TrackingJobDeleteInput,
+  TrackingJobPollInput,
+} 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; newEvents: number }> = {
+  id: 'terminal_tracking.tracking_job.create',
+  async execute(input, ctx) {
+    ensureScope(ctx, input.tenantId, input.organizationId)
+    const service = ctx.container.resolve<TerminalTrackingService>('terminalTrackingService')
+    const result = await service.createJob({
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+      terminalCode: input.terminalCode,
+      containerNumber: input.containerNumber,
+      schedule: input.schedule ?? null,
+    })
+    // Self-heal the periodic poll schedule for orgs that predate the module.
+    await ensureTerminalPollSchedule(ctx.container, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+    })
+    return { id: result.trackingJobId, newEvents: result.newEvents }
+  },
+}
+
+const deleteTrackingJob: CommandHandler<TrackingJobDeleteInput, { id: string }> = {
+  id: 'terminal_tracking.tracking_job.delete',
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const job = await em.findOne(TerminalTrackingJob, { id: input.id, deletedAt: null })
+    if (!job) throw new Error('Terminal tracking job not found')
+    ensureScope(ctx, job.tenantId, job.organizationId)
+    job.deletedAt = new Date()
+    job.status = 'deactivated'
+    await em.flush()
+    return { id: job.id }
+  },
+}
+
+const pollTrackingJob: CommandHandler<TrackingJobPollInput, { newEvents: number }> = {
+  id: 'terminal_tracking.tracking.poll_single',
+  async execute(input, ctx) {
+    const em = ctx.container.resolve<EntityManager>('em').fork()
+    const job = await em.findOne(TerminalTrackingJob, { id: input.jobId, deletedAt: null })
+    if (!job) throw new Error('Terminal tracking job not found')
+    ensureScope(ctx, job.tenantId, job.organizationId)
+    const service = ctx.container.resolve<TerminalTrackingService>('terminalTrackingService')
+    return service.pollJob(input.jobId)
+  },
+}
+
+registerCommand(createTrackingJob)
+registerCommand(deleteTrackingJob)
+registerCommand(pollTrackingJob)