@freighttech/shipment-tracking 0.6.0

package/src/modules/shipment_tracking/__tests__/webhookPayload.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Tests for webhook payload structure.
+ * Verifies that all expected fields are included in shipment payloads.
+ */
+
+import type { Shipment, TrackingEvent } from '../data/entities'
+
+// Re-create the buildShipmentPayload logic for testing
+// (The actual function is not exported from webhookService.ts)
+function buildShipmentPayload(shipment: Partial<Shipment>, trackingEvents: Partial<TrackingEvent>[]): Record<string, unknown> {
+  const latestEvent = trackingEvents.length > 0 ? trackingEvents[trackingEvents.length - 1] : null
+
+  return {
+    id: shipment.id,
+    status: shipment.status,
+    carrierCode: shipment.carrierCode,
+    containerNumber: shipment.containerNumber,
+    isoEquipmentCode: shipment.isoEquipmentCode,
+    bookingNumber: shipment.bookingNumber,
+    bolNumber: shipment.bolNumber,
+    etdTimestamps: shipment.etdTimestamps,
+    etaTimestamps: shipment.etaTimestamps,
+    atdTimestamps: shipment.atdTimestamps,
+    ataTimestamps: shipment.ataTimestamps,
+    originLocation: shipment.originLocation,
+    destinationLocation: shipment.destinationLocation,
+    currentLocationName: latestEvent?.locationName ?? null,
+    currentLocationUnlocode: latestEvent?.locationUnlocode ?? null,
+    vesselName: shipment.vesselName,
+    vesselImo: shipment.vesselImo,
+    voyageNumber: shipment.voyageNumber,
+    eventCount: shipment.eventCount,
+    lastEventAt: shipment.lastEventAt?.toISOString() ?? null,
+    extra: shipment.extra,
+    createdAt: shipment.createdAt?.toISOString() ?? null,
+    updatedAt: shipment.updatedAt?.toISOString() ?? null,
+    trackingEvents: trackingEvents.map((event) => ({
+      id: event.id,
+      source: event.source,
+      sourceEventId: event.sourceEventId,
+      eventType: event.eventType,
+      eventCode: event.eventCode,
+      eventClassifierCode: event.eventClassifierCode,
+      eventDateTime: event.eventDateTime?.toISOString() ?? null,
+      equipmentReference: event.equipmentReference,
+      isoEquipmentCode: event.isoEquipmentCode,
+      locationName: event.locationName,
+      locationUnlocode: event.locationUnlocode,
+    })),
+  }
+}
+
+describe('Webhook Payload Structure', () => {
+  describe('buildShipmentPayload', () => {
+    it('should include isoEquipmentCode in shipment payload', () => {
+      const shipment: Partial<Shipment> = {
+        id: 'shipment-123',
+        status: 'IN_TRANSIT',
+        carrierCode: 'msc',
+        containerNumber: 'MSCU1234567',
+        isoEquipmentCode: '22G1',
+        bookingNumber: 'BOOKING123',
+        vesselName: 'EXAMPLE VESSEL 01',
+        eventCount: 3,
+        createdAt: new Date('2026-02-01'),
+        updatedAt: new Date('2026-02-25'),
+      }
+
+      const trackingEvents: Partial<TrackingEvent>[] = [
+        {
+          id: 'event-1',
+          eventType: 'EQUIPMENT',
+          eventCode: 'LOAD',
+          eventClassifierCode: 'ACT',
+          equipmentReference: 'MSCU1234567',
+          isoEquipmentCode: '22G1',
+          locationName: 'Yantian',
+          locationUnlocode: 'CNYTN',
+          eventDateTime: new Date('2026-02-10'),
+        },
+      ]
+
+      const payload = buildShipmentPayload(shipment, trackingEvents)
+
+      // Verify isoEquipmentCode is in shipment-level payload
+      expect(payload.isoEquipmentCode).toBe('22G1')
+
+      // Verify isoEquipmentCode is also in each tracking event
+      const events = payload.trackingEvents as Array<{ isoEquipmentCode?: string }>
+      expect(events[0].isoEquipmentCode).toBe('22G1')
+    })
+
+    it('should handle null isoEquipmentCode', () => {
+      const shipment: Partial<Shipment> = {
+        id: 'shipment-456',
+        status: 'PENDING',
+        carrierCode: 'maersk',
+        containerNumber: 'MSKU9876543',
+        isoEquipmentCode: null,
+        createdAt: new Date('2026-02-01'),
+        updatedAt: new Date('2026-02-25'),
+      }
+
+      const payload = buildShipmentPayload(shipment, [])
+
+      expect(payload.isoEquipmentCode).toBeNull()
+    })
+
+    it('should handle undefined isoEquipmentCode', () => {
+      const shipment: Partial<Shipment> = {
+        id: 'shipment-789',
+        status: 'PENDING',
+        carrierCode: 'hapag-lloyd',
+        containerNumber: 'HLCU1111111',
+        // isoEquipmentCode not set (undefined)
+        createdAt: new Date('2026-02-01'),
+        updatedAt: new Date('2026-02-25'),
+      }
+
+      const payload = buildShipmentPayload(shipment, [])
+
+      expect(payload.isoEquipmentCode).toBeUndefined()
+    })
+
+    it('should include all ISO equipment code variants', () => {
+      // Test various ISO 6346 equipment codes
+      const testCases = [
+        { code: '22G1', description: "20' General Purpose" },
+        { code: '42G1', description: "40' General Purpose" },
+        { code: '45G1', description: "40' High Cube" },
+        { code: '22R1', description: "20' Reefer" },
+        { code: '45R1', description: "40' High Cube Reefer" },
+        { code: '2210', description: "20' Standard (numeric)" },
+        { code: '4510', description: "40' High Cube (numeric)" },
+      ]
+
+      for (const { code, description } of testCases) {
+        const shipment: Partial<Shipment> = {
+          id: `shipment-${code}`,
+          status: 'IN_TRANSIT',
+          isoEquipmentCode: code,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        }
+
+        const payload = buildShipmentPayload(shipment, [])
+        expect(payload.isoEquipmentCode).toBe(code)
+      }
+    })
+  })
+})

package/src/modules/shipment_tracking/acl.ts

@@ -0,0 +1,18 @@
+export const features = [
+  { id: 'shipment_tracking.shipments.view', title: 'View Shipments', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.shipments.manage', title: 'Manage Shipments', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.tracking_jobs.view', title: 'View Tracking Jobs', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.tracking_jobs.manage', title: 'Manage Tracking Jobs', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.carrier_configs.view', title: 'View Carrier Configs', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.carrier_configs.manage', title: 'Manage Carrier Configs', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.shipsgo_config.view', title: 'View ShipsGo Config', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.shipsgo_config.manage', title: 'Manage ShipsGo Config', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.webhooks.view', title: 'View Webhooks', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.webhooks.manage', title: 'Manage Webhooks', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.location_overrides.view', title: 'View Location Overrides', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.location_overrides.manage', title: 'Manage Location Overrides', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.settings.manage', title: 'Manage Tracking Settings', module: 'shipment_tracking' },
+  { id: 'shipment_tracking.dashboard.ships_map.view', title: 'View Ships Map Widget', module: 'shipment_tracking' },
+]
+
+export default features

package/src/modules/shipment_tracking/api/bic-configs/route.ts

@@ -0,0 +1,206 @@
+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 { BicConfig } from '../../data/entities'
+import { bicConfigUpsertSchema } from '../../data/validators'
+import {
+  createShipmentTrackingCrudOpenApi,
+  defaultOkResponseSchema,
+} from '../openapi'
+
+// ─── Metadata ────────────────────────────────────────────────
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['shipment_tracking.carrier_configs.view'] },
+  PUT: { requireAuth: true, requireFeatures: ['shipment_tracking.carrier_configs.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['shipment_tracking.carrier_configs.manage'] },
+}
+
+// ─── OpenAPI ─────────────────────────────────────────────────
+
+const upsertSchema = z.object({
+  isEnabled: z.boolean(),
+  username: z.string(),
+  password: z.string(),
+  baseUrl: z.string().optional(),
+})
+
+const bicConfigResponseSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  isEnabled: z.boolean(),
+  username: z.string(),
+  baseUrl: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+
+export const openApi = createShipmentTrackingCrudOpenApi({
+  resourceName: 'BicConfig',
+  pluralName: 'BicConfigs',
+  querySchema: z.object({}),
+  listResponseSchema: z.object({ config: bicConfigResponseSchema.nullable() }),
+  update: {
+    schema: upsertSchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Creates or updates the BIC API configuration for the current organization.',
+  },
+  del: {
+    schema: z.object({}),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Deletes the BIC 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,
+    BicConfig,
+    { organizationId, tenantId },
+    {},
+    { tenantId, organizationId },
+  )
+
+  if (!config) {
+    return NextResponse.json({ config: null })
+  }
+
+  // Return config without password
+  return NextResponse.json({
+    config: {
+      id: config.id,
+      organizationId: config.organizationId,
+      tenantId: config.tenantId,
+      isEnabled: config.isEnabled,
+      username: config.username,
+      // Password is NOT included for security
+      baseUrl: config.baseUrl,
+      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 = bicConfigUpsertSchema.parse({
+      ...(body as object),
+      organizationId,
+      tenantId,
+    })
+
+    const { result } = await commandBus.execute<typeof input, { id: string }>(
+      'shipment_tracking.bic_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.bic_config',
+        },
+      }
+    )
+
+    return NextResponse.json({ id: result?.id ?? null })
+  } catch (err) {
+    console.error('[bic-configs] PUT error:', err)
+    const message = err instanceof Error ? err.message : 'Failed to save BIC 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.bic_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.bic_config',
+        },
+      }
+    )
+
+    return NextResponse.json({ success: true })
+  } catch (err) {
+    console.error('[bic-configs] DELETE error:', err)
+    const message = err instanceof Error ? err.message : 'Failed to delete BIC config'
+    return NextResponse.json({ error: message }, { status: 400 })
+  }
+}

package/src/modules/shipment_tracking/api/bic-configs/test/route.ts

@@ -0,0 +1,108 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { BicApiClient } from '../../../lib/bic-api-client'
+import { bicConfigTestSchema } from '../../../data/validators'
+
+// ─── Metadata ────────────────────────────────────────────────
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['shipment_tracking.carrier_configs.manage'] },
+}
+
+// ─── OpenAPI ─────────────────────────────────────────────────
+
+export const openApi = {
+  POST: {
+    operationId: 'testBicConfig',
+    summary: 'Test BIC API connection',
+    description: 'Tests the BIC API credentials by attempting to authenticate.',
+    tags: ['Shipment Tracking'],
+    requestBody: {
+      content: {
+        'application/json': {
+          schema: {
+            type: 'object' as const,
+            properties: {
+              username: { type: 'string' as const },
+              password: { type: 'string' as const },
+              baseUrl: { type: 'string' as const },
+            },
+            required: ['username', 'password'],
+          },
+        },
+      },
+    },
+    responses: {
+      200: {
+        description: 'Connection test result',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object' as const,
+              properties: {
+                success: { type: 'boolean' as const },
+                message: { type: 'string' as const },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+
+// ─── POST - Test BIC API credentials ─────────────────────────
+
+export async function POST(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 })
+  }
+
+  // Parse without requiring scope fields since this is just a test
+  const parseResult = z.object({
+    username: z.string().trim().min(1),
+    password: z.string().trim().min(1),
+    baseUrl: z.string().trim().url().default('https://api.bic-code.org'),
+  }).safeParse(body)
+
+  if (!parseResult.success) {
+    return NextResponse.json(
+      { error: 'Invalid request', details: parseResult.error.flatten() },
+      { status: 400 }
+    )
+  }
+
+  const { username, password, baseUrl } = parseResult.data
+
+  try {
+    const client = new BicApiClient({
+      baseUrl,
+      username,
+      password,
+    })
+
+    await client.testConnection()
+
+    return NextResponse.json({
+      success: true,
+      message: 'BIC API connection successful',
+    })
+  } catch (err) {
+    console.error('[bic-configs/test] error:', err)
+    const message = err instanceof Error ? err.message : 'BIC API connection failed'
+    return NextResponse.json({
+      success: false,
+      message,
+    })
+  }
+}

package/src/modules/shipment_tracking/api/cargo-events/route.ts

@@ -0,0 +1,101 @@
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { z } from 'zod'
+import { TrackingEvent } from '../../data/entities'
+import { trackingEventListSchema } from '../../data/validators'
+import {
+  createShipmentTrackingCrudOpenApi,
+  createPagedListResponseSchema,
+} from '../openapi'
+
+type TrackingEventListQuery = z.infer<typeof trackingEventListSchema>
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['shipment_tracking.shipments.view'] },
+}
+
+const listFields = [
+  'id',
+  'trackingJob',
+  'source',
+  'sourceEventId',
+  'eventType',
+  'eventCode',
+  'eventClassifierCode',
+  'eventDateTime',
+  'description',
+  'equipmentReference',
+  'locationName',
+  'locationUnlocode',
+  'locationCountry',
+  'vesselName',
+  'vesselImo',
+  'voyageNumber',
+  'createdAt',
+]
+
+const buildFilters = (query: TrackingEventListQuery): Record<string, unknown> => {
+  const filters: Record<string, unknown> = {}
+
+  if (query.trackingJobId) {
+    filters.tracking_job_id = { $eq: query.trackingJobId }
+  }
+
+  if (query.equipmentReference) {
+    filters.equipmentReference = query.equipmentReference
+  }
+
+  if (query.source) {
+    filters.source = query.source
+  }
+
+  if (query.eventType) {
+    filters.eventType = query.eventType
+  }
+
+  if (query.eventCode) {
+    filters.eventCode = query.eventCode
+  }
+
+  return filters
+}
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: TrackingEvent,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: null,
+  },
+  list: {
+    schema: trackingEventListSchema,
+    fields: listFields,
+    sortFieldMap: {
+      id: 'id',
+      eventDateTime: 'event_date_time',
+      eventType: 'event_type',
+      eventCode: 'event_code',
+      createdAt: 'created_at',
+    },
+    buildFilters: async (query) => buildFilters(query),
+  },
+})
+
+export const openApi = createShipmentTrackingCrudOpenApi({
+  resourceName: 'TrackingEvent',
+  pluralName: 'TrackingEvents',
+  querySchema: trackingEventListSchema,
+  listResponseSchema: createPagedListResponseSchema(z.object({
+    id: z.string().uuid(),
+    source: z.string(),
+    eventType: z.string(),
+    eventCode: z.string(),
+    eventDateTime: z.string(),
+    equipmentReference: z.string().nullable(),
+    locationName: z.string().nullable(),
+  })),
+})
+
+export const metadata = crud.metadata
+export const GET = crud.GET