@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/__integration__/TC-TRACK-317-bct-config-test-connection.spec.ts

@@ -0,0 +1,68 @@
+import { expect, test } from '@playwright/test'
+import {
+  login,
+  createBctTerminalConfig,
+  testTerminalConfig,
+  deleteTerminalConfig,
+  type AuthSession,
+} from './helpers'
+
+/**
+ * TC-TRACK-317 — BCT (Bałtycki Terminal Kontenerowy, Gdynia) / INCOS adapter
+ * wiring, exercised through the real host app.
+ *
+ * These do NOT hit the live INCOS API — test-connection fails deterministically
+ * (connection-refused loopback host). What they prove is that the Phase-1
+ * additions are wired end-to-end through the app:
+ *  - the `basic` auth type + `bct` adapter pass create validation (validator +
+ *    entity changes),
+ *  - the `bct` adapter is registered and resolved by adapterType (registry) —
+ *    the failure is a real adapter result, never "no adapter for type",
+ *  - test-connection returns a STRUCTURED { success:false } payload, not a 500.
+ *
+ * Note: the exact failure message depends on the environment. Where tenant-data
+ * decryption of `auth_config` is active, the loopback host yields a transport
+ * error; where it is not (and creds resolve empty), the adapter's Basic-auth
+ * guard fires first. Both are structured failures — the assertions below hold
+ * either way and deliberately do not pin the first case's message text.
+ */
+test.describe('TC-TRACK-317: BCT terminal-config test connection', () => {
+  let session: AuthSession
+  const createdIds: string[] = []
+
+  test.beforeAll(async ({ request }) => {
+    session = await login(request)
+  })
+
+  test.afterEach(async ({ request }) => {
+    while (createdIds.length) {
+      await deleteTerminalConfig(request, session, createdIds.pop() as string)
+    }
+  })
+
+  test('accepts a basic/bct config and reports a structured connection failure', async ({ request }) => {
+    const { id } = await createBctTerminalConfig(request, session)
+    createdIds.push(id)
+    expect(id).toBeTruthy()
+
+    const { status, body } = await testTerminalConfig(request, session, id)
+    // A structured 200 response — the adapter resolved and failed gracefully.
+    expect(status).toBe(200)
+    expect(body.success).toBe(false)
+    expect(typeof body.message).toBe('string')
+    expect(body.message).toBeTruthy()
+    // Registration proof: it is not the generic "no adapter for type" error.
+    expect(body.message?.toLowerCase()).not.toContain('no adapter')
+  })
+
+  test('surfaces missing BCT credentials as a clear failure message', async ({ request }) => {
+    const { id } = await createBctTerminalConfig(request, session, { authConfig: {} })
+    createdIds.push(id)
+
+    const { status, body } = await testTerminalConfig(request, session, id)
+    expect(status).toBe(200)
+    expect(body.success).toBe(false)
+    // The adapter's Basic-auth guard names the missing fields.
+    expect(body.message).toContain('username/password')
+  })
+})

package/src/modules/terminal_tracking/__integration__/helpers.ts

@@ -0,0 +1,148 @@
+import type { APIRequestContext } from '@playwright/test'
+
+export const BASE_URL = process.env.BASE_URL?.trim() || 'http://localhost:3000'
+
+export interface AuthSession {
+  token: string
+  orgId: string
+  tenantId: string
+  userId?: string
+}
+
+function decodeJwt(token: string): Record<string, unknown> {
+  const payload = token.split('.')[1]
+  return JSON.parse(Buffer.from(payload, 'base64url').toString())
+}
+
+/**
+ * Log in via the host auth endpoint and return the JWT + scope claims.
+ * Credentials default to the local seed admin but are overridable via
+ * TEST_LOGIN_EMAIL / TEST_LOGIN_PASSWORD for other environments.
+ */
+export async function login(
+  request: APIRequestContext,
+  email = process.env.TEST_LOGIN_EMAIL?.trim() || 'admin@acme.com',
+  password = process.env.TEST_LOGIN_PASSWORD?.trim() || 'secret',
+): Promise<AuthSession> {
+  const form = new URLSearchParams()
+  form.set('email', email)
+  form.set('password', password)
+  const response = await request.post(`${BASE_URL}/api/auth/login`, {
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    data: form.toString(),
+  })
+  if (!response.ok()) {
+    throw new Error(`Login failed: ${response.status()} ${await response.text()}`)
+  }
+  const body = await response.json()
+  if (!body?.token) throw new Error('Login response missing token')
+  const jwt = decodeJwt(body.token)
+  return {
+    token: body.token,
+    orgId: String(jwt.orgId ?? jwt.organizationId ?? ''),
+    tenantId: String(jwt.tenantId ?? ''),
+    userId: jwt.sub ? String(jwt.sub) : undefined,
+  }
+}
+
+export function authHeaders(token: string): Record<string, string> {
+  return { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }
+}
+
+const CONFIG_API = `${BASE_URL}/api/terminal_tracking/terminal-configs`
+
+/** A unique terminal code so parallel/repeat runs never collide on the unique index. */
+export function uniqueTerminalCode(prefix = 'gcttest'): string {
+  const stamp = `${Date.now().toString().slice(-6)}${Math.floor(Math.random() * 1_000).toString().padStart(3, '0')}`
+  return `${prefix}-${stamp}`.toLowerCase()
+}
+
+/**
+ * Build a GCT terminal-config create payload. `baseUrl` defaults to a
+ * connection-refused loopback so `testConnection` fails fast and deterministically
+ * without touching a real terminal. `organizationId`/`tenantId` are injected
+ * server-side from the auth scope, so they are intentionally omitted here.
+ */
+export function buildGctConfigPayload(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    terminalCode: uniqueTerminalCode(),
+    adapterType: 'gct',
+    displayName: 'GCT Test',
+    baseUrl: 'http://127.0.0.1:1',
+    authType: 'gct_token',
+    endpoints: { unit: '/gctapi/GetContainerDetails' },
+    authConfig: { companyCode: 'ACME', loginName: 'user', loginPassword: 'secret' },
+    unlocode: 'PLGDY',
+    ...overrides,
+  }
+}
+
+/**
+ * Build a BCT/INCOS terminal-config create payload. Like the GCT builder,
+ * `baseUrl` defaults to a connection-refused loopback so `testConnection` fails
+ * fast without touching the real INCOS host. Auth is HTTP Basic
+ * (`{ username, password }`). Daily-cap rate limit mirrors production
+ * (10000 requests / 86400s).
+ */
+export function buildBctConfigPayload(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    terminalCode: uniqueTerminalCode('bcttest'),
+    adapterType: 'bct',
+    displayName: 'BCT Test',
+    baseUrl: 'http://127.0.0.1:1',
+    authType: 'basic',
+    endpoints: { unit: '/rest-container/container', vessel: '/rest-vesselvisit/vesselvisit' },
+    authConfig: { username: 'user', password: 'secret' },
+    rateLimitRequests: 10000,
+    rateLimitWindowSeconds: 86400,
+    unlocode: 'PLBCT',
+    ...overrides,
+  }
+}
+
+export async function createTerminalConfig(
+  request: APIRequestContext,
+  session: AuthSession,
+  overrides: Record<string, unknown> = {},
+  build: (o: Record<string, unknown>) => Record<string, unknown> = buildGctConfigPayload,
+): Promise<{ id: string; payload: Record<string, unknown> }> {
+  const payload = build(overrides)
+  const res = await request.post(CONFIG_API, { headers: authHeaders(session.token), data: payload })
+  if (!res.ok()) throw new Error(`Create config failed: ${res.status()} ${await res.text()}`)
+  const body = (await res.json()) as { id: string }
+  return { id: body.id, payload }
+}
+
+/** Create a BCT/INCOS terminal config (Basic auth), reusing the shared POST. */
+export async function createBctTerminalConfig(
+  request: APIRequestContext,
+  session: AuthSession,
+  overrides: Record<string, unknown> = {},
+): Promise<{ id: string; payload: Record<string, unknown> }> {
+  return createTerminalConfig(request, session, overrides, buildBctConfigPayload)
+}
+
+export async function testTerminalConfig(
+  request: APIRequestContext,
+  session: AuthSession,
+  id: string,
+): Promise<{ status: number; body: { success?: boolean; message?: string; latencyMs?: number } }> {
+  const res = await request.post(`${CONFIG_API}/test`, {
+    headers: authHeaders(session.token),
+    data: { id },
+  })
+  return { status: res.status(), body: res.ok() ? await res.json() : { message: await res.text() } }
+}
+
+/** Best-effort soft-delete used in teardown; never throws. */
+export async function deleteTerminalConfig(
+  request: APIRequestContext,
+  session: AuthSession,
+  id: string,
+): Promise<void> {
+  try {
+    await request.delete(CONFIG_API, { headers: authHeaders(session.token), data: { id } })
+  } catch {
+    // teardown best-effort
+  }
+}

package/src/modules/terminal_tracking/__integration__/meta.ts

@@ -0,0 +1,4 @@
+export const integrationMeta = {
+  description: 'Terminal-tracking integration coverage',
+  dependsOnModules: ['terminal_tracking'],
+}

package/src/modules/terminal_tracking/acl.ts

@@ -0,0 +1,10 @@
+export const features = [
+  { id: 'terminal_tracking.terminal_configs.view', title: 'View Terminal Configs', module: 'terminal_tracking' },
+  { id: 'terminal_tracking.terminal_configs.manage', title: 'Manage Terminal Configs', module: 'terminal_tracking' },
+  { id: 'terminal_tracking.tracking_jobs.view', title: 'View Terminal Tracking Jobs', module: 'terminal_tracking' },
+  { id: 'terminal_tracking.tracking_jobs.manage', title: 'Manage Terminal Tracking Jobs', module: 'terminal_tracking' },
+  { id: 'terminal_tracking.events.view', title: 'View Terminal Events', module: 'terminal_tracking' },
+  { id: 'terminal_tracking.settings.manage', title: 'Manage Terminal Tracking Settings', module: 'terminal_tracking' },
+]
+
+export default features

package/src/modules/terminal_tracking/api/openapi.ts

@@ -0,0 +1,28 @@
+import { type ZodTypeAny } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  createCrudOpenApiFactory,
+  createPagedListResponseSchema as createSharedPagedListResponseSchema,
+  defaultCreateResponseSchema as sharedDefaultCreateResponseSchema,
+  defaultOkResponseSchema as sharedDefaultOkResponseSchema,
+  type CrudOpenApiOptions,
+} from '@open-mercato/shared/lib/openapi/crud'
+
+export const defaultCreateResponseSchema = sharedDefaultCreateResponseSchema
+export const defaultOkResponseSchema = sharedDefaultOkResponseSchema
+
+export function createPagedListResponseSchema(itemSchema: ZodTypeAny) {
+  return createSharedPagedListResponseSchema(itemSchema, { paginationMetaOptional: true })
+}
+
+const buildTerminalTrackingCrudOpenApi = createCrudOpenApiFactory({
+  defaultTag: 'Terminal Tracking',
+  defaultCreateResponseSchema,
+  defaultOkResponseSchema,
+  makeListDescription: ({ pluralLower }) =>
+    `Returns a paginated collection of ${pluralLower} scoped to the authenticated organization.`,
+})
+
+export function createTerminalTrackingCrudOpenApi(options: CrudOpenApiOptions): OpenApiRouteDoc {
+  return buildTerminalTrackingCrudOpenApi(options)
+}

package/src/modules/terminal_tracking/api/terminal-configs/route.ts

@@ -0,0 +1,140 @@
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { z } from 'zod'
+import { TerminalConfig } from '../../data/entities'
+import {
+  terminalConfigListSchema,
+  terminalConfigCreateSchema,
+  terminalConfigUpdateSchema,
+} from '../../data/validators'
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import {
+  createTerminalTrackingCrudOpenApi,
+  createPagedListResponseSchema,
+  defaultOkResponseSchema,
+} from '../openapi'
+import { withScopedPayload } from '../utils'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+
+const rawBodySchema = z.object({}).passthrough()
+
+type ListQuery = z.infer<typeof terminalConfigListSchema>
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['terminal_tracking.terminal_configs.view'] },
+  POST: { requireAuth: true, requireFeatures: ['terminal_tracking.terminal_configs.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['terminal_tracking.terminal_configs.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['terminal_tracking.terminal_configs.manage'] },
+}
+
+const listFields = [
+  'id',
+  'terminalCode',
+  'adapterType',
+  'displayName',
+  'baseUrl',
+  'authType',
+  'unlocode',
+  'isActive',
+  'createdAt',
+  'updatedAt',
+]
+
+const buildFilters = (query: ListQuery): Record<string, unknown> => {
+  const filters: Record<string, unknown> = { deletedAt: null }
+  if (query.terminalCode) filters.terminalCode = query.terminalCode
+  if (query.isActive !== undefined) {
+    const parsed = parseBooleanToken(query.isActive)
+    if (parsed !== null) filters.isActive = parsed
+  }
+  return filters
+}
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: TerminalConfig,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: terminalConfigListSchema,
+    fields: listFields,
+    sortFieldMap: {
+      id: 'id',
+      terminalCode: 'terminal_code',
+      isActive: 'is_active',
+      createdAt: 'created_at',
+    },
+    buildFilters: async (query) => buildFilters(query),
+  },
+  actions: {
+    create: {
+      commandId: 'terminal_tracking.terminal_config.create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return terminalConfigCreateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 201,
+    },
+    update: {
+      commandId: 'terminal_tracking.terminal_config.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return terminalConfigUpdateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 200,
+    },
+    delete: {
+      commandId: 'terminal_tracking.terminal_config.delete',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const body = (raw as any)?.body ?? raw ?? {}
+        const scoped = withScopedPayload(body, ctx, translate)
+        return { id: body.id, ...scoped }
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 200,
+    },
+  },
+})
+
+export const openApi = createTerminalTrackingCrudOpenApi({
+  resourceName: 'TerminalConfig',
+  pluralName: 'TerminalConfigs',
+  querySchema: terminalConfigListSchema,
+  listResponseSchema: createPagedListResponseSchema(
+    z.object({
+      id: z.string().uuid(),
+      terminalCode: z.string(),
+      adapterType: z.string(),
+      displayName: z.string(),
+      isActive: z.boolean(),
+    }),
+  ),
+  create: { schema: rawBodySchema, description: 'Creates a new terminal configuration.' },
+  update: {
+    schema: rawBodySchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Updates an existing terminal configuration.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Deletes a terminal configuration.',
+  },
+})
+
+export const metadata = crud.metadata
+export const GET = crud.GET
+export const POST = crud.POST
+export const PUT = crud.PUT
+export const DELETE = crud.DELETE

package/src/modules/terminal_tracking/api/terminal-configs/test/route.ts

@@ -0,0 +1,64 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['terminal_tracking.terminal_configs.manage'] },
+}
+
+const testSchema = z.object({ id: z.string().uuid() })
+
+export async function POST(request: NextRequest) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth || !auth.orgId || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 })
+  }
+
+  const parsed = testSchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid request', details: parsed.error.flatten() }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+  const commandBus = container.resolve('commandBus') as CommandBus
+  const selectedOrgId = scope?.selectedId ?? auth.orgId
+  const tenantId = auth.tenantId
+
+  try {
+    const { result } = await commandBus.execute<
+      { id: string; tenantId: string; organizationId: string },
+      { success: boolean; message: string; latencyMs?: number }
+    >('terminal_tracking.terminal_config.test', {
+      input: { id: parsed.data.id, tenantId, organizationId: selectedOrgId },
+      ctx: {
+        container,
+        auth,
+        organizationScope: scope,
+        selectedOrganizationId: selectedOrgId ?? null,
+        organizationIds: scope?.filterIds ?? (selectedOrgId ? [selectedOrgId] : null),
+        request,
+      },
+      metadata: {
+        tenantId: tenantId ?? null,
+        organizationId: selectedOrgId ?? null,
+        resourceKind: 'terminal_tracking.terminal_config',
+        resourceId: parsed.data.id,
+      },
+    })
+    return NextResponse.json(result)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Failed to test terminal config'
+    return NextResponse.json({ error: message }, { status: 400 })
+  }
+}

package/src/modules/terminal_tracking/api/tracking-jobs/details/route.ts

@@ -0,0 +1,116 @@
+import { NextRequest, NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { TerminalTrackingJob, TerminalEvent, TerminalVesselVisit } from '../../../data/entities'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['terminal_tracking.tracking_jobs.view'] },
+}
+
+export async function GET(request: NextRequest) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth || !auth.orgId || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const id = new URL(request.url).searchParams.get('id')
+  if (!id) {
+    return NextResponse.json({ error: 'Missing id' }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+  const em = container.resolve('em') as EntityManager
+  const orgIds = scope?.filterIds ?? [auth.orgId]
+
+  const job = await em.findOne(TerminalTrackingJob, {
+    id,
+    tenantId: auth.tenantId,
+    organizationId: { $in: orgIds },
+    deletedAt: null,
+  })
+  if (!job) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 })
+  }
+
+  const events = await em.find(
+    TerminalEvent,
+    { job: job.id, tenantId: auth.tenantId },
+    { orderBy: { eventDateTime: 'asc' } },
+  )
+
+  // Resolved vessel visits for this container's legs, keyed by visit ref.
+  const visitRefs = [
+    ...new Set(
+      events.flatMap((e) => [e.visitRefIn, e.visitRefOut]).filter((r): r is string => !!r),
+    ),
+  ]
+  const visits = visitRefs.length
+    ? await em.find(TerminalVesselVisit, {
+        tenantId: auth.tenantId,
+        organizationId: { $in: orgIds },
+        terminalCode: job.terminalCode,
+        visitRef: { $in: visitRefs },
+      })
+    : []
+  const vesselVisits = Object.fromEntries(
+    visits.map((v) => [
+      v.visitRef,
+      {
+        visitRef: v.visitRef,
+        vesselName: v.vesselName ?? null,
+        ibVoyage: v.ibVoyage ?? null,
+        obVoyage: v.obVoyage ?? null,
+        line: v.line ?? null,
+        phase: v.phase ?? null,
+        eta: v.eta ? v.eta.toISOString() : null,
+        etd: v.etd ? v.etd.toISOString() : null,
+        ata: v.ata ? v.ata.toISOString() : null,
+        atd: v.atd ? v.atd.toISOString() : null,
+        beginReceive: v.beginReceive ? v.beginReceive.toISOString() : null,
+        dryCutoff: v.dryCutoff ? v.dryCutoff.toISOString() : null,
+      },
+    ]),
+  )
+
+  return NextResponse.json({
+    job: {
+      id: job.id,
+      terminalCode: job.terminalCode,
+      containerNumber: job.containerNumber,
+      status: job.status,
+      lastPollAt: job.lastPollAt ? job.lastPollAt.toISOString() : null,
+      nextPollAt: job.nextPollAt ? job.nextPollAt.toISOString() : null,
+      retryCount: job.retryCount,
+      errorHistory: job.errorHistory ?? [],
+      createdAt: job.createdAt ? job.createdAt.toISOString() : null,
+    },
+    events: events.map((e) => ({
+      id: e.id,
+      ufvGkey: e.ufvGkey,
+      sourceEventId: e.sourceEventId,
+      eventType: e.eventType,
+      eventCode: e.eventCode,
+      eventClassifierCode: e.eventClassifierCode ?? null,
+      eventDateTime: e.eventDateTime ? e.eventDateTime.toISOString() : null,
+      transitState: e.transitState ?? null,
+      visitState: e.visitState ?? null,
+      facilityCode: e.facilityCode ?? null,
+      facilityCodeListProvider: e.facilityCodeListProvider ?? null,
+      unlocode: e.unlocode ?? null,
+      visitRefIn: e.visitRefIn ?? null,
+      visitRefOut: e.visitRefOut ?? null,
+      vesselName: e.vesselName ?? null,
+      voyageNumber: e.voyageNumber ?? null,
+      modeOfTransport: e.modeOfTransport ?? null,
+      seals: e.seals ?? null,
+      vgmWeightKg: e.vgmWeightKg ?? null,
+      impediments: e.impediments ?? null,
+      loadedAt: e.loadedAt ? e.loadedAt.toISOString() : null,
+      rawData: e.rawData ?? null,
+    })),
+    vesselVisits,
+  })
+}

package/src/modules/terminal_tracking/api/tracking-jobs/poll/route.ts

@@ -0,0 +1,64 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['terminal_tracking.tracking_jobs.manage'] },
+}
+
+const pollSchema = z.object({ id: z.string().uuid() })
+
+export async function POST(request: NextRequest) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth || !auth.orgId || !auth.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 })
+  }
+
+  const parsed = pollSchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid request', details: parsed.error.flatten() }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+  const commandBus = container.resolve('commandBus') as CommandBus
+  const selectedOrgId = scope?.selectedId ?? auth.orgId
+  const tenantId = auth.tenantId
+
+  try {
+    const { result } = await commandBus.execute<
+      { jobId: string; tenantId: string; organizationId: string },
+      { newEvents: number; updatedEvents: number }
+    >('terminal_tracking.tracking.poll_single', {
+      input: { jobId: parsed.data.id, tenantId, organizationId: selectedOrgId },
+      ctx: {
+        container,
+        auth,
+        organizationScope: scope,
+        selectedOrganizationId: selectedOrgId ?? null,
+        organizationIds: scope?.filterIds ?? (selectedOrgId ? [selectedOrgId] : null),
+        request,
+      },
+      metadata: {
+        tenantId: tenantId ?? null,
+        organizationId: selectedOrgId ?? null,
+        resourceKind: 'terminal_tracking.tracking_job',
+        resourceId: parsed.data.id,
+      },
+    })
+    return NextResponse.json(result)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Failed to poll terminal tracking job'
+    return NextResponse.json({ error: message }, { status: 400 })
+  }
+}