@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/api/shipments/route.ts

@@ -0,0 +1,197 @@
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { z } from 'zod'
+import { Shipment } from '../../data/entities'
+import { shipmentListSchema, shipmentCreateSchema, shipmentUpdateSchema } from '../../data/validators'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import {
+  createShipmentTrackingCrudOpenApi,
+  createPagedListResponseSchema,
+  defaultOkResponseSchema,
+} from '../openapi'
+import { withScopedPayload } from '../utils'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+
+const rawBodySchema = z.object({}).passthrough()
+
+type ShipmentListQuery = z.infer<typeof shipmentListSchema>
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['shipment_tracking.shipments.view'] },
+  POST: { requireAuth: true, requireFeatures: ['shipment_tracking.shipments.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['shipment_tracking.shipments.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['shipment_tracking.shipments.manage'] },
+}
+
+const listFields = [
+  'id',
+  'status',
+  'carrierCode',
+  'containerNumber',
+  'bookingNumber',
+  'isoEquipmentCode',
+  'bolNumber',
+  // Multi-source timestamp arrays
+  'etdTimestamps',
+  'etaTimestamps',
+  'atdTimestamps',
+  'ataTimestamps',
+  // Location data (JSONB)
+  'originLocation',
+  'destinationLocation',
+  // Vessel info
+  'vesselName',
+  'vesselImo',
+  'voyageNumber',
+  'eventCount',
+  // Denormalized route & events (JSONB)
+  'routeStops',
+  'cargoEvents',
+  // Aggregated seals (JSONB)
+  'seals',
+  // Tracking job relation (for fetching events - kept for backward compatibility)
+  'trackingJob',
+  'createdAt',
+  'updatedAt',
+]
+
+const buildFilters = (query: ShipmentListQuery): Record<string, unknown> => {
+  const filters: Record<string, unknown> = { deletedAt: null }
+
+  if (query.id) {
+    filters.id = query.id
+  }
+
+  const search = query.search?.trim()
+  if (search && search.length > 0) {
+    const escaped = escapeLikePattern(search)
+    const pattern = `%${escaped}%`
+    filters.$or = [
+      { containerNumber: { $ilike: pattern } },
+      { bookingNumber: { $ilike: pattern } },
+      { bolNumber: { $ilike: pattern } },
+      { carrierCode: { $ilike: pattern } },
+      { vesselName: { $ilike: pattern } },
+      // HEDGE-101 — JSONB nested property search, as NESTED OBJECTS.
+      //
+      // `origin_location` / `destination_location` are `jsonb` columns, not
+      // relations. A dotted string key (`'originLocation.name'`) is read by
+      // MikroORM as a RELATION PATH, so it emitted a condition against a table
+      // that was never joined and the query died with
+      // `missing FROM-clause entry for table "originLocation"` — a hard 500 on
+      // every keystroke. The nested-object form is what compiles to
+      // `"origin_location"->>'name'`.
+      //
+      // The condition is only added when `q` is non-empty, which is why the
+      // route looked healthy until the first search: this path had never worked.
+      { originLocation: { name: { $ilike: pattern } } },
+      { originLocation: { unlocode: { $ilike: pattern } } },
+      { destinationLocation: { name: { $ilike: pattern } } },
+      { destinationLocation: { unlocode: { $ilike: pattern } } },
+    ]
+  }
+
+  if (query.status) {
+    filters.status = query.status
+  }
+
+  if (query.carrierCode) {
+    filters.carrierCode = query.carrierCode
+  }
+
+  return filters
+}
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: Shipment,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  list: {
+    schema: shipmentListSchema,
+    fields: listFields,
+    sortFieldMap: {
+      id: 'id',
+      status: 'status',
+      carrierCode: 'carrier_code',
+      containerNumber: 'container_number',
+      bookingNumber: 'booking_number',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+    },
+    buildFilters: async (query) => buildFilters(query),
+  },
+  actions: {
+    create: {
+      commandId: 'shipment_tracking.shipment.create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return shipmentCreateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 201,
+    },
+    update: {
+      commandId: 'shipment_tracking.shipment.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return shipmentUpdateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 200,
+    },
+    delete: {
+      commandId: 'shipment_tracking.shipment.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 = createShipmentTrackingCrudOpenApi({
+  resourceName: 'Shipment',
+  pluralName: 'Shipments',
+  querySchema: shipmentListSchema,
+  listResponseSchema: createPagedListResponseSchema(z.object({
+    id: z.string().uuid(),
+    status: z.string(),
+    carrierCode: z.string().nullable(),
+    containerNumber: z.string().nullable(),
+    bookingNumber: z.string().nullable(),
+    bolNumber: z.string().nullable(),
+  })),
+  create: {
+    schema: rawBodySchema,
+    description: 'Creates a new shipment.',
+  },
+  update: {
+    schema: rawBodySchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Updates an existing shipment by id.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Soft-deletes a shipment by id.',
+  },
+})
+
+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/shipment_tracking/api/shipsgo-configs/route.ts

@@ -0,0 +1,215 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+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 type { CommandBus } from '@open-mercato/shared/lib/commands'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { ShipsGoConfig } from '../../data/entities'
+import { shipsGoConfigUpsertSchema } from '../../data/validators'
+import {
+  createShipmentTrackingCrudOpenApi,
+  defaultOkResponseSchema,
+} from '../openapi'
+
+// ─── Metadata ────────────────────────────────────────────────
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['shipment_tracking.shipsgo_config.view'] },
+  PUT: { requireAuth: true, requireFeatures: ['shipment_tracking.shipsgo_config.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['shipment_tracking.shipsgo_config.manage'] },
+}
+
+// ─── OpenAPI ─────────────────────────────────────────────────
+
+const upsertSchema = z.object({
+  isEnabled: z.boolean(),
+  apiToken: z.string(),
+  baseUrl: z.string().optional(),
+  oceanEnabled: z.boolean().optional(),
+  airEnabled: z.boolean().optional(),
+  rateLimitRequests: z.number().optional(),
+  rateLimitWindowSeconds: z.number().optional(),
+})
+
+const shipsGoConfigResponseSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  isEnabled: z.boolean(),
+  baseUrl: z.string(),
+  oceanEnabled: z.boolean(),
+  airEnabled: z.boolean(),
+  rateLimitRequests: z.number(),
+  rateLimitWindowSeconds: z.number(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+
+export const openApi = createShipmentTrackingCrudOpenApi({
+  resourceName: 'ShipsGoConfig',
+  pluralName: 'ShipsGoConfigs',
+  querySchema: z.object({}),
+  listResponseSchema: z.object({ config: shipsGoConfigResponseSchema.nullable() }),
+  update: {
+    schema: upsertSchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Creates or updates the ShipsGo API configuration for the current organization.',
+  },
+  del: {
+    schema: z.object({}),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Deletes the ShipsGo API configuration.',
+  },
+})
+
+// ─── GET - Retrieve current config ───────────────────────────
+
+export async function GET(request: NextRequest) {
+  const auth = await getAuthFromRequest(request)
+
+  if (!auth?.orgId || !auth?.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+  const em = container.resolve('em') as EntityManager
+
+  const organizationId = scope?.selectedId ?? auth.orgId
+  const tenantId = auth.tenantId
+
+  const config = await findOneWithDecryption(
+    em,
+    ShipsGoConfig,
+    { organizationId, tenantId, deletedAt: null },
+    {},
+    { tenantId, organizationId },
+  )
+
+  if (!config) {
+    return NextResponse.json({ config: null })
+  }
+
+  // Return config without the API token
+  return NextResponse.json({
+    config: {
+      id: config.id,
+      organizationId: config.organizationId,
+      tenantId: config.tenantId,
+      isEnabled: config.isEnabled,
+      // apiToken is NOT included for security
+      baseUrl: config.baseUrl,
+      oceanEnabled: config.oceanEnabled,
+      airEnabled: config.airEnabled,
+      rateLimitRequests: config.rateLimitRequests,
+      rateLimitWindowSeconds: config.rateLimitWindowSeconds,
+      createdAt: config.createdAt.toISOString(),
+      updatedAt: config.updatedAt.toISOString(),
+    },
+  })
+}
+
+// ─── PUT - Upsert config ─────────────────────────────────────
+
+export async function PUT(request: NextRequest) {
+  const auth = await getAuthFromRequest(request)
+
+  if (!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 container = await createRequestContainer()
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+  const commandBus = container.resolve('commandBus') as CommandBus
+
+  const organizationId = scope?.selectedId ?? auth.orgId
+  const tenantId = auth.tenantId
+
+  try {
+    const input = shipsGoConfigUpsertSchema.parse({
+      ...(body as object),
+      organizationId,
+      tenantId,
+    })
+
+    const { result } = await commandBus.execute<typeof input, { id: string }>(
+      'shipment_tracking.shipsgo_config.upsert',
+      {
+        input,
+        ctx: {
+          container,
+          auth,
+          organizationScope: scope,
+          selectedOrganizationId: organizationId ?? null,
+          organizationIds: scope?.filterIds ?? (organizationId ? [organizationId] : null),
+          request,
+        },
+        metadata: {
+          tenantId: tenantId ?? null,
+          organizationId: organizationId ?? null,
+          resourceKind: 'shipment_tracking.shipsgo_config',
+        },
+      }
+    )
+
+    return NextResponse.json({ id: result?.id ?? null })
+  } catch (err) {
+    console.error('[shipsgo-configs] PUT error:', err)
+    const message = err instanceof Error ? err.message : 'Failed to save ShipsGo config'
+    return NextResponse.json({ error: message }, { status: 400 })
+  }
+}
+
+// ─── DELETE - Remove config ──────────────────────────────────
+
+export async function DELETE(request: NextRequest) {
+  const auth = await getAuthFromRequest(request)
+
+  if (!auth?.orgId || !auth?.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+  const commandBus = container.resolve('commandBus') as CommandBus
+
+  const organizationId = scope?.selectedId ?? auth.orgId
+  const tenantId = auth.tenantId
+
+  try {
+    await commandBus.execute<{ organizationId: string; tenantId: string }, { success: boolean }>(
+      'shipment_tracking.shipsgo_config.delete',
+      {
+        input: { organizationId, tenantId },
+        ctx: {
+          container,
+          auth,
+          organizationScope: scope,
+          selectedOrganizationId: organizationId ?? null,
+          organizationIds: scope?.filterIds ?? (organizationId ? [organizationId] : null),
+          request,
+        },
+        metadata: {
+          tenantId: tenantId ?? null,
+          organizationId: organizationId ?? null,
+          resourceKind: 'shipment_tracking.shipsgo_config',
+        },
+      }
+    )
+
+    return NextResponse.json({ success: true })
+  } catch (err) {
+    console.error('[shipsgo-configs] DELETE error:', err)
+    const message = err instanceof Error ? err.message : 'Failed to delete ShipsGo config'
+    return NextResponse.json({ error: message }, { status: 400 })
+  }
+}

package/src/modules/shipment_tracking/api/tracking-jobs/route.ts

@@ -0,0 +1,149 @@
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { z } from 'zod'
+import { TrackingJob } from '../../data/entities'
+import { trackingJobListSchema, trackingJobCreateSchema, trackingJobUpdateSchema } from '../../data/validators'
+import {
+  createShipmentTrackingCrudOpenApi,
+  createPagedListResponseSchema,
+  defaultOkResponseSchema,
+} from '../openapi'
+import { withScopedPayload } from '../utils'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+
+const rawBodySchema = z.object({}).passthrough()
+
+type TrackingJobListQuery = z.infer<typeof trackingJobListSchema>
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['shipment_tracking.tracking_jobs.view'] },
+  POST: { requireAuth: true, requireFeatures: ['shipment_tracking.tracking_jobs.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['shipment_tracking.tracking_jobs.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['shipment_tracking.tracking_jobs.manage'] },
+}
+
+const listFields = [
+  'id',
+  'carrierCode',
+  'referenceType',
+  'referenceValue',
+  'status',
+  'nextPollAt',
+  'lastPollAt',
+  'retryCount',
+  'createdAt',
+  'updatedAt',
+]
+
+const buildFilters = (query: TrackingJobListQuery): Record<string, unknown> => {
+  const filters: Record<string, unknown> = {}
+
+  if (query.status) {
+    filters.status = query.status
+  }
+
+  if (query.carrierCode) {
+    filters.carrierCode = query.carrierCode
+  }
+
+  if (query.referenceType) {
+    filters.referenceType = query.referenceType
+  }
+
+  if (query.referenceValue) {
+    filters.referenceValue = query.referenceValue
+  }
+
+  return filters
+}
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: TrackingJob,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+  },
+  list: {
+    schema: trackingJobListSchema,
+    fields: listFields,
+    sortFieldMap: {
+      id: 'id',
+      carrierCode: 'carrier_code',
+      status: 'status',
+      nextPollAt: 'next_poll_at',
+      lastPollAt: 'last_poll_at',
+      createdAt: 'created_at',
+    },
+    buildFilters: async (query) => buildFilters(query),
+  },
+  actions: {
+    create: {
+      commandId: 'shipment_tracking.tracking_job.create',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return trackingJobCreateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 201,
+    },
+    update: {
+      commandId: 'shipment_tracking.tracking_job.pause',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        return trackingJobUpdateSchema.parse(scoped)
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 200,
+    },
+    delete: {
+      commandId: 'shipment_tracking.tracking_job.deactivate',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate)
+        const id = (raw as any)?.body?.id ?? (raw as any)?.query?.id
+        return { id, ...scoped }
+      },
+      response: ({ result }) => ({ id: result?.id ?? null }),
+      status: 200,
+    },
+  },
+})
+
+export const openApi = createShipmentTrackingCrudOpenApi({
+  resourceName: 'TrackingJob',
+  pluralName: 'TrackingJobs',
+  querySchema: trackingJobListSchema,
+  listResponseSchema: createPagedListResponseSchema(z.object({
+    id: z.string().uuid(),
+    carrierCode: z.string(),
+    referenceType: z.string(),
+    referenceValue: z.string(),
+    status: z.string(),
+  })),
+  create: {
+    schema: rawBodySchema,
+    description: 'Creates a new tracking job. The system will auto-discover containers from carrier events.',
+  },
+  update: {
+    schema: rawBodySchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Pauses a tracking job.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Deactivates a tracking job.',
+  },
+})
+
+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/shipment_tracking/api/tracking-jobs/sync/route.ts

@@ -0,0 +1,116 @@
+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: ['shipment_tracking.tracking_jobs.manage'] },
+}
+
+const syncSchema = z.object({
+  id: z.string().uuid(),
+})
+
+export const openApi = {
+  POST: {
+    operationId: 'triggerTrackingJobSync',
+    summary: 'Trigger sync for a tracking job',
+    description: 'Immediately polls the carrier for new events on the specified tracking job.',
+    tags: ['ShipmentTracking'],
+    requestBody: {
+      content: {
+        'application/json': {
+          schema: {
+            type: 'object',
+            required: ['id'],
+            properties: {
+              id: { type: 'string', format: 'uuid' },
+            },
+          },
+        },
+      },
+    },
+    responses: {
+      200: {
+        description: 'Sync result',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                newEvents: { type: 'number' },
+                shipmentsCreated: { type: 'number' },
+                shipmentsUpdated: { type: 'number' },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+
+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 = syncSchema.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; shipmentsCreated: number; shipmentsUpdated: number }
+    >('shipment_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: 'shipment_tracking.tracking_job',
+        resourceId: parsed.data.id,
+      },
+    })
+
+    return NextResponse.json(result)
+  } catch (error) {
+    console.error('[tracking-jobs/sync] error:', error)
+    const message = error instanceof Error ? error.message : 'Failed to sync tracking job'
+    return NextResponse.json({ error: message }, { status: 400 })
+  }
+}

package/src/modules/shipment_tracking/api/utils.ts

@@ -0,0 +1,10 @@
+import { createScopedApiHelpers } from '@open-mercato/shared/lib/api/scoped'
+
+const { withScopedPayload, parseScopedCommandInput } = createScopedApiHelpers({
+  messages: {
+    tenantRequired: { key: 'shipment_tracking.errors.tenant_required', fallback: 'Tenant context is required' },
+    organizationRequired: { key: 'shipment_tracking.errors.organization_required', fallback: 'Organization context is required' },
+  },
+})
+
+export { withScopedPayload, parseScopedCommandInput }