@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/data/entities.ts

@@ -0,0 +1,386 @@
+import { Collection, OptionalProps } from '@mikro-orm/core'
+import { Entity, PrimaryKey, Property, Index, Unique, ManyToOne, OneToMany } from '@mikro-orm/decorators/legacy'
+
+// ─── Enums / shared types ────────────────────────────────────
+// Re-declared locally on purpose: terminal_tracking must NOT depend on
+// shipment_tracking internals. The cross-module contract is the event payload.
+
+export type TerminalEventType = 'EQUIPMENT' | 'TRANSPORT'
+export type TerminalEventClassifierCode = 'ACT' | 'PLN' | 'EST'
+export type TerminalEventSource = 'terminal'
+export type FacilityCodeProvider = 'SMDG' | 'BIC'
+export type TerminalModeOfTransport = 'VESSEL' | 'RAIL' | 'TRUCK' | 'BARGE'
+
+export type TerminalAuthType = 'oauth2_password' | 'oauth2_client_credentials' | 'gct_token' | 'basic'
+
+export type TerminalTrackingJobStatus = 'active' | 'paused' | 'deactivated' | 'failed' | 'completed'
+
+export type TerminalEndpoints = {
+  unit: string
+  vessel?: string
+  trainVisits?: string
+}
+
+export type TerminalSealInfo = {
+  number: string
+  type?: string | null
+  source?: string | null
+}
+
+// ─── TerminalConfig ──────────────────────────────────────────
+// Per (org, tenant, terminalCode) terminal definition + tenant credentials.
+// `auth_config` is encrypted at rest (see encryption.ts). `client_id`,
+// `token_url`, `scope` are NOT secrets and stay as plain columns.
+
+@Entity({ tableName: 'terminal_tracking_terminal_configs' })
+@Index({ name: 'tt_terminal_configs_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+@Unique({ name: 'tt_terminal_configs_code_uniq', properties: ['organizationId', 'tenantId', 'terminalCode'] })
+export class TerminalConfig {
+  [OptionalProps]?:
+    | 'isActive'
+    | 'createdAt'
+    | 'updatedAt'
+    | 'deletedAt'
+    | 'rateLimitRequests'
+    | 'rateLimitWindowSeconds'
+    | 'vesselCacheTtlSeconds'
+    | 'proxyUrl'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  // Lowercase terminal identifier, e.g. 'bct'
+  @Property({ name: 'terminal_code', type: 'text' })
+  terminalCode!: string
+
+  // Selects the adapter implementation from the registry, e.g. 'n4'
+  @Property({ name: 'adapter_type', type: 'text' })
+  adapterType!: string
+
+  @Property({ name: 'display_name', type: 'text' })
+  displayName!: string
+
+  @Property({ name: 'base_url', type: 'text' })
+  baseUrl!: string
+
+  // Optional HTTP(S) forward-proxy URL for this terminal's API calls (used to
+  // egress from a whitelisted IP). Null = direct. No embedded credentials —
+  // secure the proxy by IP allowlist.
+  @Property({ name: 'proxy_url', type: 'text', nullable: true })
+  proxyUrl?: string | null
+
+  @Property({ name: 'endpoints', type: 'jsonb' })
+  endpoints!: TerminalEndpoints
+
+  @Property({ name: 'auth_type', type: 'text' })
+  authType!: TerminalAuthType
+
+  // OAuth token endpoint (may include a policy query param, e.g. ?p=b2c_1_ropc_login)
+  @Property({ name: 'token_url', type: 'text', nullable: true })
+  tokenUrl?: string | null
+
+  @Property({ name: 'scope', type: 'text', nullable: true })
+  scope?: string | null
+
+  // Public OAuth client id (NOT a secret)
+  @Property({ name: 'client_id', type: 'text', nullable: true })
+  clientId?: string | null
+
+  // Encrypted at rest: { username, password } (ROPC) or { clientSecret }
+  @Property({ name: 'auth_config', type: 'jsonb', nullable: true })
+  authConfig?: Record<string, unknown> | null
+
+  @Property({ name: 'rate_limit_requests', type: 'integer', default: 200 })
+  rateLimitRequests: number = 200
+
+  @Property({ name: 'rate_limit_window_seconds', type: 'integer', default: 60 })
+  rateLimitWindowSeconds: number = 60
+
+  // TTL (seconds) for the cached /VESSEL visit lookup; null = module default.
+  @Property({ name: 'vessel_cache_ttl_seconds', type: 'integer', nullable: true })
+  vesselCacheTtlSeconds?: number | null
+
+  // ─── Matching fields (resolve a facility -> this terminal) ────
+  @Property({ name: 'unlocode', type: 'text', length: 5, nullable: true })
+  unlocode?: string | null
+
+  @Property({ name: 'bic_codes', type: 'jsonb', nullable: true })
+  bicCodes?: string[] | null
+
+  @Property({ name: 'smdg_codes', type: 'jsonb', nullable: true })
+  smdgCodes?: string[] | null
+
+  @Property({ name: 'name_aliases', type: 'jsonb', nullable: true })
+  nameAliases?: string[] | null
+
+  @Property({ name: 'is_active', type: 'boolean', default: true })
+  isActive: boolean = true
+
+  @Property({ name: 'created_at', type: Date, defaultRaw: 'now()' })
+  createdAt!: Date
+
+  @Property({ name: 'updated_at', type: Date, defaultRaw: 'now()', onUpdate: () => new Date() })
+  updatedAt!: Date
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+// ─── TerminalTrackingJob ─────────────────────────────────────
+// A module-owned watchlist unit: a container number tracked at one terminal.
+
+@Entity({ tableName: 'terminal_tracking_jobs' })
+@Index({ name: 'tt_jobs_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+@Index({ name: 'tt_jobs_status_idx', properties: ['status'] })
+@Index({ name: 'tt_jobs_next_poll_idx', properties: ['nextPollAt'] })
+@Index({ name: 'tt_jobs_container_idx', properties: ['containerNumber'] })
+export class TerminalTrackingJob {
+  [OptionalProps]?:
+    | 'createdAt'
+    | 'updatedAt'
+    | 'deletedAt'
+    | 'status'
+    | 'retryCount'
+    | 'emptyReadyAt'
+    | 'holdsClearedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'terminal_code', type: 'text' })
+  terminalCode!: string
+
+  @Property({ name: 'container_number', type: 'text' })
+  containerNumber!: string
+
+  @Property({ type: 'text', default: 'active' })
+  status: TerminalTrackingJobStatus = 'active'
+
+  // JSON array of scheduled poll dates (ISO); null = follow the module default cadence
+  @Property({ type: 'jsonb', nullable: true })
+  schedule?: string[] | null
+
+  @Property({ name: 'next_poll_at', type: Date, nullable: true })
+  nextPollAt?: Date | null
+
+  @Property({ name: 'last_poll_at', type: Date, nullable: true })
+  lastPollAt?: Date | null
+
+  @Property({ name: 'retry_count', type: 'integer', default: 0 })
+  retryCount: number = 0
+
+  @Property({ name: 'error_history', type: 'jsonb', nullable: true })
+  errorHistory?: Array<{ date: string; message: string }> | null
+
+  // One-shot availability markers. Set the first time this container satisfies
+  // the availability rule at the terminal, so the corresponding notification
+  // fires exactly once. `empty_ready` = export empty collectable;
+  // `holds_cleared` = import container's blocking holds removed.
+  @Property({ name: 'empty_ready_at', type: Date, nullable: true })
+  emptyReadyAt?: Date | null
+
+  @Property({ name: 'holds_cleared_at', type: Date, nullable: true })
+  holdsClearedAt?: Date | null
+
+  @Property({ name: 'created_at', type: Date, defaultRaw: 'now()' })
+  createdAt!: Date
+
+  @Property({ name: 'updated_at', type: Date, defaultRaw: 'now()', onUpdate: () => new Date() })
+  updatedAt!: Date
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+
+  @OneToMany(() => TerminalEvent, (e) => e.job)
+  events = new Collection<TerminalEvent>(this)
+}
+
+// ─── TerminalEvent ───────────────────────────────────────────
+// A normalized terminal event. `source_event_id` embeds the N4 Ufv_Gkey so
+// that multiple Unit Facility Visits per container (import + export legs)
+// remain distinct under the unique constraint.
+
+@Entity({ tableName: 'terminal_tracking_events' })
+@Index({ name: 'tt_events_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+@Index({ name: 'tt_events_job_idx', properties: ['job'] })
+@Index({ name: 'tt_events_container_idx', properties: ['containerNumber'] })
+@Index({ name: 'tt_events_event_date_idx', properties: ['eventDateTime'] })
+@Unique({ name: 'tt_events_source_event_uniq', properties: ['job', 'source', 'sourceEventId'] })
+export class TerminalEvent {
+  [OptionalProps]?: 'createdAt' | 'source'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @ManyToOne(() => TerminalTrackingJob, { fieldName: 'job_id' })
+  job!: TerminalTrackingJob
+
+  @Property({ type: 'text', default: 'terminal' })
+  source: TerminalEventSource = 'terminal'
+
+  // '{terminalCode}:{ufvGkey}:{eventCode}'
+  @Property({ name: 'source_event_id', type: 'text' })
+  sourceEventId!: string
+
+  @Property({ name: 'event_type', type: 'text' })
+  eventType!: TerminalEventType
+
+  @Property({ name: 'event_code', type: 'text' })
+  eventCode!: string
+
+  @Property({ name: 'event_classifier_code', type: 'text', nullable: true })
+  eventClassifierCode?: TerminalEventClassifierCode | null
+
+  @Property({ name: 'event_date_time', type: Date })
+  eventDateTime!: Date
+
+  @Property({ name: 'container_number', type: 'text' })
+  containerNumber!: string
+
+  @Property({ name: 'ufv_gkey', type: 'text' })
+  ufvGkey!: string
+
+  @Property({ name: 'transit_state', type: 'text', nullable: true })
+  transitState?: string | null
+
+  @Property({ name: 'visit_state', type: 'text', nullable: true })
+  visitState?: string | null
+
+  // ─── Location ─────────────────────────────────────────────
+  @Property({ name: 'facility_code', type: 'text', nullable: true })
+  facilityCode?: string | null
+
+  @Property({ name: 'facility_code_list_provider', type: 'text', nullable: true })
+  facilityCodeListProvider?: FacilityCodeProvider | null
+
+  @Property({ name: 'unlocode', type: 'text', length: 5, nullable: true })
+  unlocode?: string | null
+
+  // ─── Visit references (for vessel/train enrichment) ───────
+  @Property({ name: 'visit_ref_in', type: 'text', nullable: true })
+  visitRefIn?: string | null
+
+  @Property({ name: 'visit_ref_out', type: 'text', nullable: true })
+  visitRefOut?: string | null
+
+  // ─── Transport ────────────────────────────────────────────
+  @Property({ name: 'vessel_name', type: 'text', nullable: true })
+  vesselName?: string | null
+
+  @Property({ name: 'voyage_number', type: 'text', nullable: true })
+  voyageNumber?: string | null
+
+  @Property({ name: 'mode_of_transport', type: 'text', nullable: true })
+  modeOfTransport?: TerminalModeOfTransport | null
+
+  // ─── Cargo extras ─────────────────────────────────────────
+  @Property({ name: 'seals', type: 'jsonb', nullable: true })
+  seals?: TerminalSealInfo[] | null
+
+  @Property({ name: 'vgm_weight_kg', type: 'float', nullable: true })
+  vgmWeightKg?: number | null
+
+  @Property({ name: 'impediments', type: 'jsonb', nullable: true })
+  impediments?: string[] | null
+
+  // When the container was loaded onto its transport (N4 `Loaded` column),
+  // parsed regardless of current transit state. Export = onto vessel; import =
+  // onto road/rail.
+  @Property({ name: 'loaded_at', type: Date, nullable: true })
+  loadedAt?: Date | null
+
+  @Property({ name: 'raw_data', type: 'jsonb', nullable: true })
+  rawData?: Record<string, unknown> | null
+
+  @Property({ name: 'created_at', type: Date, defaultRaw: 'now()' })
+  createdAt!: Date
+}
+
+// ─── TerminalVesselVisit ─────────────────────────────────────
+// A resolved N4 vessel visit (from /VESSEL), keyed by visit ref and shared by
+// every container on that visit. Doubles as a TTL cache: `updatedAt` is the
+// freshness signal. Upsert-only (no soft delete); no FK to job.
+
+@Entity({ tableName: 'terminal_tracking_vessel_visits' })
+@Index({ name: 'tt_vessel_visits_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+@Index({ name: 'tt_vessel_visits_visit_ref_idx', properties: ['visitRef'] })
+@Unique({ name: 'tt_vessel_visits_uniq', properties: ['organizationId', 'tenantId', 'terminalCode', 'visitRef'] })
+export class TerminalVesselVisit {
+  [OptionalProps]?: 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'terminal_code', type: 'text' })
+  terminalCode!: string
+
+  // The N4 visit ref (the `Visit` column); equals an event's visitRefIn/Out.
+  @Property({ name: 'visit_ref', type: 'text' })
+  visitRef!: string
+
+  @Property({ name: 'vessel_name', type: 'text', nullable: true })
+  vesselName?: string | null
+
+  @Property({ name: 'ib_voyage', type: 'text', nullable: true })
+  ibVoyage?: string | null
+
+  @Property({ name: 'ob_voyage', type: 'text', nullable: true })
+  obVoyage?: string | null
+
+  @Property({ name: 'line', type: 'text', nullable: true })
+  line?: string | null
+
+  @Property({ name: 'phase', type: 'text', nullable: true })
+  phase?: string | null
+
+  @Property({ name: 'eta', type: Date, nullable: true })
+  eta?: Date | null
+
+  @Property({ name: 'etd', type: Date, nullable: true })
+  etd?: Date | null
+
+  @Property({ name: 'ata', type: Date, nullable: true })
+  ata?: Date | null
+
+  @Property({ name: 'atd', type: Date, nullable: true })
+  atd?: Date | null
+
+  @Property({ name: 'begin_receive', type: Date, nullable: true })
+  beginReceive?: Date | null
+
+  @Property({ name: 'dry_cutoff', type: Date, nullable: true })
+  dryCutoff?: Date | null
+
+  @Property({ name: 'raw_data', type: 'jsonb', nullable: true })
+  rawData?: Record<string, unknown> | null
+
+  @Property({ name: 'created_at', type: Date, defaultRaw: 'now()' })
+  createdAt!: Date
+
+  @Property({ name: 'updated_at', type: Date, defaultRaw: 'now()', onUpdate: () => new Date() })
+  updatedAt!: Date
+}

package/src/modules/terminal_tracking/data/validators.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod'
+
+const endpointsSchema = z.object({
+  unit: z.string().min(1),
+  vessel: z.string().optional(),
+  trainVisits: z.string().optional(),
+})
+
+const authTypeSchema = z.enum(['oauth2_password', 'oauth2_client_credentials', 'gct_token', 'basic'])
+
+// ─── TerminalConfig ──────────────────────────────────────────
+
+export const terminalConfigCreateSchema = z.object({
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  terminalCode: z.string().min(1).transform((s) => s.toLowerCase()),
+  adapterType: z.string().min(1),
+  displayName: z.string().min(1),
+  baseUrl: z.string().url(),
+  proxyUrl: z.string().url().nullish(),
+  endpoints: endpointsSchema.optional(),
+  authType: authTypeSchema,
+  tokenUrl: z.string().url().nullish(),
+  scope: z.string().nullish(),
+  clientId: z.string().nullish(),
+  authConfig: z.record(z.string(), z.unknown()).nullish(),
+  rateLimitRequests: z.number().int().positive().optional(),
+  rateLimitWindowSeconds: z.number().int().positive().optional(),
+  unlocode: z.string().length(5).nullish(),
+  bicCodes: z.array(z.string()).nullish(),
+  smdgCodes: z.array(z.string()).nullish(),
+  nameAliases: z.array(z.string()).nullish(),
+  isActive: z.boolean().optional(),
+})
+export type TerminalConfigCreateInput = z.infer<typeof terminalConfigCreateSchema>
+
+export const terminalConfigUpdateSchema = terminalConfigCreateSchema
+  .partial()
+  .extend({ id: z.string().uuid() })
+export type TerminalConfigUpdateInput = z.infer<typeof terminalConfigUpdateSchema>
+
+export const terminalConfigDeleteSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+})
+export type TerminalConfigDeleteInput = z.infer<typeof terminalConfigDeleteSchema>
+
+export const terminalConfigTestSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+})
+export type TerminalConfigTestInput = z.infer<typeof terminalConfigTestSchema>
+
+export const terminalConfigListSchema = z.object({
+  page: z.coerce.number().int().positive().optional(),
+  pageSize: z.coerce.number().int().positive().max(100).optional(),
+  sortField: z.string().optional(),
+  sortDir: z.enum(['asc', 'desc']).optional(),
+  terminalCode: z.string().optional(),
+  isActive: z.string().optional(),
+})
+
+// ─── TerminalTrackingJob ─────────────────────────────────────
+
+export const trackingJobCreateSchema = z.object({
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  terminalCode: z.string().min(1).transform((s) => s.toLowerCase()),
+  containerNumber: z.string().min(4).transform((s) => s.toUpperCase()),
+  schedule: z.array(z.string()).nullish(),
+})
+export type TrackingJobCreateInput = z.infer<typeof trackingJobCreateSchema>
+
+export const trackingJobDeleteSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+})
+export type TrackingJobDeleteInput = z.infer<typeof trackingJobDeleteSchema>
+
+export const trackingJobPollSchema = z.object({
+  jobId: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+})
+export type TrackingJobPollInput = z.infer<typeof trackingJobPollSchema>
+
+export const trackingJobListSchema = z.object({
+  page: z.coerce.number().int().positive().optional(),
+  // DynamicTable sends both `limit` and `pageSize` (same value); accept either.
+  pageSize: z.coerce.number().int().positive().max(100).optional(),
+  limit: z.coerce.number().int().positive().max(100).optional(),
+  sortField: z.string().optional(),
+  sortDir: z.enum(['asc', 'desc']).optional(),
+  terminalCode: z.string().optional(),
+  containerNumber: z.string().optional(),
+  status: z.string().optional(),
+  // DynamicTable filter popover — JSON-stringified FilterRow[] sent as `?filters=`
+  filters: z.string().optional(),
+})
+
+// ─── TerminalVesselVisit ─────────────────────────────────────
+
+export const vesselVisitListSchema = z.object({
+  page: z.coerce.number().int().positive().optional(),
+  pageSize: z.coerce.number().int().positive().max(100).optional(),
+  visitRef: z.string().optional(),
+  containerNumber: z.string().optional().transform((s) => (s ? s.toUpperCase() : s)),
+  terminalCode: z.string().optional(),
+})
+export type VesselVisitListInput = z.infer<typeof vesselVisitListSchema>

package/src/modules/terminal_tracking/di.ts

@@ -0,0 +1,46 @@
+import { asClass } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { TerminalRegistry } from './services/terminalRegistry'
+import { TerminalTrackingService } from './services/terminalTrackingService'
+import { TerminalMatcherService } from './services/terminalMatcherService'
+import { registerAllAdapters } from './lib/adapters'
+
+export function register(container: AppContainer) {
+  // Adapter registry (singleton - adapters registered once)
+  container.register({
+    terminalTrackingRegistry: asClass(TerminalRegistry).singleton(),
+  })
+
+  // Tracking service (poll loop, dedup, emit)
+  container.register({
+    terminalTrackingService: {
+      resolve: () => {
+        const cache = container.resolve<any>('cache')
+        return new TerminalTrackingService({
+          em: () => container.resolve('em'),
+          eventBus: container.resolve('eventBus'),
+          terminalRegistry: container.resolve('terminalTrackingRegistry'),
+          cacheService: {
+            get: (key: string) => cache.get(key),
+            set: (key: string, value: string, ttlSeconds?: number) =>
+              cache.set(key, value, ttlSeconds ? { ttl: ttlSeconds * 1000 } : undefined),
+          },
+        })
+      },
+    },
+  })
+
+  // Terminal matcher (fuzzy name + exact BIC/SMDG/UNLOCODE)
+  container.register({
+    terminalMatcherService: {
+      resolve: () =>
+        new TerminalMatcherService({
+          em: () => container.resolve('em'),
+        }),
+    },
+  })
+
+  // Register built-in adapters
+  const registry = container.resolve<TerminalRegistry>('terminalTrackingRegistry')
+  registerAllAdapters(registry)
+}

package/src/modules/terminal_tracking/encryption.ts

@@ -0,0 +1,12 @@
+import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
+
+export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
+  {
+    entityId: 'terminal_tracking:terminal_config',
+    fields: [
+      { field: 'auth_config' },
+    ],
+  },
+]
+
+export default defaultEncryptionMaps

package/src/modules/terminal_tracking/events.ts

@@ -0,0 +1,48 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+const events = [
+  // ─── Tracking job lifecycle (internal) ─────────────────────────
+  { id: 'terminal_tracking.tracking_job.created', label: 'Terminal Tracking Job Created', entity: 'tracking_job', category: 'crud', excludeFromTriggers: true },
+  { id: 'terminal_tracking.tracking_job.updated', label: 'Terminal Tracking Job Updated', entity: 'tracking_job', category: 'crud', excludeFromTriggers: true },
+  { id: 'terminal_tracking.tracking_job.failed', label: 'Terminal Tracking Job Failed', entity: 'tracking_job', category: 'lifecycle', excludeFromTriggers: true },
+  { id: 'terminal_tracking.tracking_job.poll_failed', label: 'Terminal Tracking Job Poll Failed', entity: 'tracking_job', category: 'lifecycle', excludeFromTriggers: true },
+
+  // ─── Raw terminal event (the bridge trigger) ───────────────────
+  { id: 'terminal_tracking.terminal_event.created', label: 'Terminal Event Created', entity: 'terminal_event', category: 'crud' },
+  { id: 'terminal_tracking.terminal_event.updated', label: 'Terminal Event Updated', entity: 'terminal_event', category: 'crud' },
+
+  // ─── Semantic milestones (per container) ───────────────────────
+  { id: 'terminal_tracking.equipment.gate_in', label: 'Container Gate In (Terminal)', entity: 'terminal_event', category: 'lifecycle' },
+  { id: 'terminal_tracking.equipment.discharged', label: 'Container Discharged (Terminal)', entity: 'terminal_event', category: 'lifecycle' },
+  { id: 'terminal_tracking.equipment.loaded', label: 'Container Loaded (Terminal)', entity: 'terminal_event', category: 'lifecycle' },
+  { id: 'terminal_tracking.transport.departed', label: 'Container Departed (Terminal)', entity: 'terminal_event', category: 'lifecycle' },
+
+  // ─── Availability milestones (fire once per container) ─────────
+  // Export empty released for collection: empty container in the yard with no
+  // movement-blocking holds.
+  { id: 'terminal_tracking.equipment.empty_ready', label: 'Empty Container Ready For Pickup (Terminal)', entity: 'terminal_event', category: 'lifecycle' },
+  // Import container's blocking holds removed: it became collectable (transition
+  // from blocked → unblocked while in the yard).
+  { id: 'terminal_tracking.equipment.holds_cleared', label: 'Import Holds Cleared (Terminal)', entity: 'terminal_event', category: 'lifecycle' },
+  // The raw impediment (hold) set changed between polls. Unlike the two
+  // one-shot availability events above, this fires every poll the set changes
+  // (including first appearance with holds) so downstream consumers can mirror
+  // the current hold list. Payload carries `impediments: string[]`.
+  { id: 'terminal_tracking.equipment.holds_updated', label: 'Container Holds Updated (Terminal)', entity: 'terminal_event', category: 'lifecycle' },
+  // The per-mode load/pickup STOP flags (Stop-Vsl / Stop-Road / Stop-Rail)
+  // changed between polls. Like `holds_updated`, fires every poll the set
+  // changes (incl. first appearance) so downstream consumers can mirror the
+  // current stops. Payload carries `stops: { vsl, road, rail: boolean | null }`.
+  { id: 'terminal_tracking.equipment.stops_updated', label: 'Container Load Stops Updated (Terminal)', entity: 'terminal_event', category: 'lifecycle' },
+] as const
+
+export const eventsConfig = createModuleEvents({
+  moduleId: 'terminal_tracking',
+  events,
+})
+
+export const emitTerminalTrackingEvent = eventsConfig.emit
+
+export type TerminalTrackingEventId = typeof events[number]['id']
+
+export default eventsConfig