@freighttech/shipment-tracking 0.6.0

package/generated/entities/tracking_event/index.ts

@@ -0,0 +1,60 @@
+// AUTO-GENERATED by scripts/generate-entity-fields.mjs (HEDGE-168). Do not edit.
+//
+// One file per entity, named `toSnake(ClassName)` — NOT the table name. Each
+// export is a database column name, mirroring what `mercato generate` writes
+// for `@open-mercato/*` packages. `loadStandaloneGeneratedPackageEntities()`
+// reads these back to build the host app's `entity-fields-registry.ts`, which
+// is what the Encryption and Translation managers list fields from.
+//
+// Regenerate with `node scripts/generate-entity-fields.mjs --all`; the package
+// build does it for you. Guarded by
+// `apps/web/src/__tests__/entity-fields-registry-contract.test.ts`.
+export const id = "id";
+export const organization_id = "organization_id";
+export const tenant_id = "tenant_id";
+export const tracking_job = "tracking_job";
+export const source = "source";
+export const source_event_id = "source_event_id";
+export const event_type = "event_type";
+export const event_code = "event_code";
+export const event_classifier_code = "event_classifier_code";
+export const event_date_time = "event_date_time";
+export const event_date_time_offset = "event_date_time_offset";
+export const description = "description";
+export const raw_data = "raw_data";
+export const equipment_reference = "equipment_reference";
+export const iso_equipment_code = "iso_equipment_code";
+export const empty_indicator_code = "empty_indicator_code";
+export const is_transshipment_move = "is_transshipment_move";
+export const location_name = "location_name";
+export const location_unlocode = "location_unlocode";
+export const location_country = "location_country";
+export const region_name_pl = "region_name_pl";
+export const region_name_en = "region_name_en";
+export const facility_code = "facility_code";
+export const facility_code_list_provider = "facility_code_list_provider";
+export const facility_type_code = "facility_type_code";
+export const facility_address = "facility_address";
+export const latitude = "latitude";
+export const longitude = "longitude";
+export const transport_call_reference = "transport_call_reference";
+export const mode_of_transport = "mode_of_transport";
+export const vessel_name = "vessel_name";
+export const vessel_imo = "vessel_imo";
+export const voyage_number = "voyage_number";
+export const carrier_service_code = "carrier_service_code";
+export const carrier_export_voyage_number = "carrier_export_voyage_number";
+export const carrier_import_voyage_number = "carrier_import_voyage_number";
+export const universal_service_reference = "universal_service_reference";
+export const universal_export_voyage_reference = "universal_export_voyage_reference";
+export const universal_import_voyage_reference = "universal_import_voyage_reference";
+export const port_visit_reference = "port_visit_reference";
+export const related_document_references = "related_document_references";
+export const event_created_date_time = "event_created_date_time";
+export const retracted_event_id = "retracted_event_id";
+export const publisher_name = "publisher_name";
+export const publisher_role = "publisher_role";
+export const delay_reason_code = "delay_reason_code";
+export const change_remark = "change_remark";
+export const seals = "seals";
+export const created_at = "created_at";

package/generated/entities/tracking_job/index.ts

@@ -0,0 +1,33 @@
+// AUTO-GENERATED by scripts/generate-entity-fields.mjs (HEDGE-168). Do not edit.
+//
+// One file per entity, named `toSnake(ClassName)` — NOT the table name. Each
+// export is a database column name, mirroring what `mercato generate` writes
+// for `@open-mercato/*` packages. `loadStandaloneGeneratedPackageEntities()`
+// reads these back to build the host app's `entity-fields-registry.ts`, which
+// is what the Encryption and Translation managers list fields from.
+//
+// Regenerate with `node scripts/generate-entity-fields.mjs --all`; the package
+// build does it for you. Guarded by
+// `apps/web/src/__tests__/entity-fields-registry-contract.test.ts`.
+export const id = "id";
+export const organization_id = "organization_id";
+export const tenant_id = "tenant_id";
+export const provider = "provider";
+export const mode = "mode";
+export const provider_shipment_id = "provider_shipment_id";
+export const carrier_code = "carrier_code";
+export const reference_type = "reference_type";
+export const reference_value = "reference_value";
+export const origin_unlocode = "origin_unlocode";
+export const destination_unlocode = "destination_unlocode";
+export const status = "status";
+export const schedule = "schedule";
+export const next_poll_at = "next_poll_at";
+export const last_poll_at = "last_poll_at";
+export const retry_count = "retry_count";
+export const error_history = "error_history";
+export const created_at = "created_at";
+export const updated_at = "updated_at";
+export const deleted_at = "deleted_at";
+export const shipments = "shipments";
+export const events = "events";

package/generated/entities/webhook/index.ts

@@ -0,0 +1,22 @@
+// AUTO-GENERATED by scripts/generate-entity-fields.mjs (HEDGE-168). Do not edit.
+//
+// One file per entity, named `toSnake(ClassName)` — NOT the table name. Each
+// export is a database column name, mirroring what `mercato generate` writes
+// for `@open-mercato/*` packages. `loadStandaloneGeneratedPackageEntities()`
+// reads these back to build the host app's `entity-fields-registry.ts`, which
+// is what the Encryption and Translation managers list fields from.
+//
+// Regenerate with `node scripts/generate-entity-fields.mjs --all`; the package
+// build does it for you. Guarded by
+// `apps/web/src/__tests__/entity-fields-registry-contract.test.ts`.
+export const id = "id";
+export const organization_id = "organization_id";
+export const tenant_id = "tenant_id";
+export const url = "url";
+export const events_subscribed = "events_subscribed";
+export const hmac_secret = "hmac_secret";
+export const is_active = "is_active";
+export const created_at = "created_at";
+export const updated_at = "updated_at";
+export const deleted_at = "deleted_at";
+export const deliveries = "deliveries";

package/generated/entities/webhook_delivery/index.ts

@@ -0,0 +1,22 @@
+// AUTO-GENERATED by scripts/generate-entity-fields.mjs (HEDGE-168). Do not edit.
+//
+// One file per entity, named `toSnake(ClassName)` — NOT the table name. Each
+// export is a database column name, mirroring what `mercato generate` writes
+// for `@open-mercato/*` packages. `loadStandaloneGeneratedPackageEntities()`
+// reads these back to build the host app's `entity-fields-registry.ts`, which
+// is what the Encryption and Translation managers list fields from.
+//
+// Regenerate with `node scripts/generate-entity-fields.mjs --all`; the package
+// build does it for you. Guarded by
+// `apps/web/src/__tests__/entity-fields-registry-contract.test.ts`.
+export const id = "id";
+export const webhook = "webhook";
+export const event_type = "event_type";
+export const status = "status";
+export const retry_count = "retry_count";
+export const next_retry_at = "next_retry_at";
+export const payload = "payload";
+export const response_status = "response_status";
+export const response_body = "response_body";
+export const error_message = "error_message";
+export const created_at = "created_at";

package/generated/entities.ids.generated.ts

@@ -0,0 +1,47 @@
+// Entity ids for `@freighttech/shipment-tracking` — HAND-MAINTAINED and AUTHORITATIVE.
+//
+// This header used to say "local typecheck stub", owned at runtime by apps/web.
+// Both halves were false, and HEDGE-164 is what that cost. Nothing regenerates
+// this file — `yarn generate` rewrites `generated/` only for modules declared
+// `from: '@app'`. And it is not merely a typecheck aid: because
+// `@open-mercato/core` installs as a real directory rather than a workspace
+// symlink, `@open-mercato/cli` runs in STANDALONE mode, where
+// `loadStandaloneGeneratedPackageEntities()` reads THIS file as the package's
+// entity list and uses it INSTEAD of parsing `data/entities.ts`.
+//
+// An entity missing here is therefore missing from the host app's `E`, and `E`
+// is a runtime registry rather than a bag of types: it backs the custom-field
+// entity picker, query-index coverage and reindex, attachment assignment,
+// dashboard widget sources and encryption field resolution. The entity's table,
+// migrations and repositories keep working the whole time, which is why the
+// failure reads as "the feature was never built" instead of as an error.
+//
+// One key per exported class in `data/entities.ts`, keyed `toSnake(ClassName)`
+// with NO pluralisation — `InvoiceOrderLine` is `invoice_order_line`, never the
+// `tableName`. Namespaces for OTHER modules are typecheck-only; the generator
+// reads `E['<this module id>']` and ignores the rest.
+//
+// The mechanism in full, and the guard that fails the gate when this file and
+// `data/entities.ts` drift apart:
+// `apps/web/src/__tests__/entity-ids-registry-contract.test.ts`.
+
+export const M = {
+  shipment_tracking: 'shipment_tracking',
+} as const
+
+export const E = {
+  shipment_tracking: {
+    tracking_job: 'shipment_tracking:tracking_job',
+    shipment: 'shipment_tracking:shipment',
+    tracking_event: 'shipment_tracking:tracking_event',
+    carrier_config: 'shipment_tracking:carrier_config',
+    bic_config: 'shipment_tracking:bic_config',
+    shipsgo_config: 'shipment_tracking:shipsgo_config',
+    webhook: 'shipment_tracking:webhook',
+    location_override: 'shipment_tracking:location_override',
+    webhook_delivery: 'shipment_tracking:webhook_delivery',
+  },
+} as const
+
+export type KnownModuleId = keyof typeof M
+export type KnownEntities = typeof E

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@freighttech/shipment-tracking",
+  "version": "0.6.0",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "generated",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./modules/shipment_tracking/*": {
+      "types": [
+        "./src/modules/shipment_tracking/*.ts",
+        "./src/modules/shipment_tracking/*.tsx"
+      ],
+      "default": "./dist/modules/shipment_tracking/*.js"
+    },
+    "./modules/shipment_tracking/*.json": "./src/modules/shipment_tracking/*.json"
+  },
+  "imports": {
+    "#generated/entities.ids.generated": {
+      "types": "./generated/entities.ids.generated.ts",
+      "default": "./generated/entities.ids.generated.ts"
+    }
+  },
+  "peerDependencies": {
+    "@freighttech/ui": "^0.13.0",
+    "@mikro-orm/core": "^7.0.17",
+    "@mikro-orm/decorators": "^7.0.17",
+    "@mikro-orm/migrations": "^7.0.17",
+    "@mikro-orm/postgresql": "^7.0.17",
+    "@open-mercato/cache": "0.6.2",
+    "@open-mercato/core": "0.6.2",
+    "@open-mercato/events": "0.6.2",
+    "@open-mercato/queue": "0.6.2",
+    "@open-mercato/scheduler": "0.6.2",
+    "@open-mercato/shared": "0.6.2",
+    "@opentelemetry/api": "^1.9.0",
+    "@react-google-maps/api": "^2.20.6",
+    "@tanstack/react-query": "^5.90.12",
+    "awilix": "^12.0.5",
+    "lucide-react": "^0.556.0",
+    "nats": "^2.28.2",
+    "next": "^16.2.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@open-mercato/scheduler": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/google.maps": "^3.58.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "npx --no-install vitest run",
+    "test:watch": "npx --no-install vitest",
+    "build": "node ../../scripts/build-package.mjs",
+    "prepack": "node ../../scripts/build-package.mjs"
+  }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @freighttech/shipment-tracking
+ *
+ * Ocean container shipment tracking with pluggable carrier adapters and webhooks
+ */
+
+export {
+  Shipment,
+  TrackingJob,
+  TrackingEvent,
+  CarrierConfig,
+  Webhook,
+  WebhookDelivery,
+} from './modules/shipment_tracking/data/entities'
+
+export type {
+  ShipmentTimestampEntry,
+  TimestampSource,
+  TimestampType,
+} from './modules/shipment_tracking/data/entities'
+
+export type { CarrierAdapter, CarrierAdapterTestResult } from './modules/shipment_tracking/lib/carrier-adapter'
+export type { ShipmentStatus } from './modules/shipment_tracking/lib/status-machine'
+export { deriveShipmentStatus } from './modules/shipment_tracking/lib/status-machine'
+export { extractShipmentTimes } from './modules/shipment_tracking/lib/time-extraction'
+
+// Timestamp utilities for multi-source tracking
+export {
+  getLatestTimestamp,
+  getPrimaryTimestampValue,
+  getPrimaryTimestampOffset,
+  createTimestampEntry,
+  addTimestampEntry,
+  mergeExtractedTimestamps,
+  hasTimestamps,
+  getTimestampsBySource,
+  getTimestampHistory,
+} from './modules/shipment_tracking/lib/timestamp-utils'
+export type { ComputedTimestamp } from './modules/shipment_tracking/lib/timestamp-utils'

package/src/modules/shipment_tracking/__integration__/TC-TRACK-410-shipsgo-config-api.spec.ts

@@ -0,0 +1,133 @@
+/**
+ * TC-TRACK-410 — ShipsGo config API contract & token-hiding.
+ *
+ * Verifies the per-tenant ShipsGo configuration route
+ *   packages/shipment-tracking/src/modules/shipment_tracking/api/shipsgo-configs/route.ts
+ *
+ * Acceptance:
+ *   - Unauthenticated GET/PUT/DELETE → 401.
+ *   - PUT upserts the config for the caller's org/tenant (200, returns id).
+ *   - GET returns the stored config but NEVER echoes the apiToken (the token is
+ *     encrypted at rest and must not leave the server) — the security invariant.
+ *   - PUT with the "__UNCHANGED__" sentinel keeps the config without rotating
+ *     the token (still 200, config still present + enabled).
+ *   - DELETE removes it; a subsequent GET returns { config: null }.
+ *
+ * This is the only surface of the ShipsGo feature with a self-contained HTTP
+ * contract: a ShipsGo *tracking job* cannot be created from the public API
+ * (it is routed to internally on unsupported-carrier legs), and register→poll
+ * would require a live, credit-spending ShipsGo account — those behaviours are
+ * pinned by the unit/service tests (shipsgo-provider / shipsgo-poll /
+ * shipsgo-client / shipsgo-mapper), not here.
+ *
+ * Fully self-contained: no fixtures, no hardcoded IDs. The config is a singleton
+ * per org/tenant, so the test snapshots any pre-existing config and restores it
+ * in teardown to stay order-independent.
+ */
+
+import { expect, test, type APIRequestContext } from '@playwright/test'
+import { login } from '@open-mercato/core/helpers/integration/auth'
+
+const ENDPOINT = '/api/shipment_tracking/shipsgo-configs'
+
+type ShipsGoConfig = {
+  id: string
+  isEnabled: boolean
+  baseUrl: string
+  oceanEnabled: boolean
+  airEnabled: boolean
+  apiToken?: string
+}
+
+async function getConfig(api: APIRequestContext): Promise<ShipsGoConfig | null> {
+  const res = await api.get(ENDPOINT)
+  if (!res.ok()) return null
+  const body = (await res.json().catch(() => null)) as { config?: ShipsGoConfig | null } | null
+  return body?.config ?? null
+}
+
+test.describe('TC-TRACK-410: ShipsGo config API', () => {
+  let snapshot: ShipsGoConfig | null = null
+
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'superadmin')
+    // Snapshot any existing config so we can restore singleton state afterwards.
+    snapshot = await getConfig(page.request)
+  })
+
+  test.afterEach(async ({ page }) => {
+    // Restore: delete our test config, then re-apply the original if there was one.
+    await page.request.delete(ENDPOINT).catch(() => null)
+    if (snapshot) {
+      await page.request
+        .put(ENDPOINT, {
+          data: {
+            isEnabled: snapshot.isEnabled,
+            apiToken: '__UNCHANGED__', // original token was never exposed; keep whatever was there
+            baseUrl: snapshot.baseUrl,
+            oceanEnabled: snapshot.oceanEnabled,
+            airEnabled: snapshot.airEnabled,
+          },
+        })
+        .catch(() => null)
+    }
+  })
+
+  test('rejects unauthenticated access with 401', async ({ request }) => {
+    // `request` here is the bare context (no login/cookies).
+    const res = await request.get(ENDPOINT)
+    expect(res.status()).toBe(401)
+  })
+
+  test('upserts config and never returns the apiToken on GET', async ({ page }) => {
+    const put = await page.request.put(ENDPOINT, {
+      data: {
+        isEnabled: true,
+        apiToken: 'secret-token-value',
+        baseUrl: 'https://api.shipsgo.com/v2',
+        oceanEnabled: true,
+        airEnabled: false,
+      },
+    })
+    expect(put.ok()).toBeTruthy()
+
+    const config = await getConfig(page.request)
+    expect(config).not.toBeNull()
+    expect(config!.isEnabled).toBe(true)
+    expect(config!.oceanEnabled).toBe(true)
+    expect(config!.airEnabled).toBe(false)
+    expect(config!.baseUrl).toBe('https://api.shipsgo.com/v2')
+
+    // The security invariant: the token must never travel back to the client.
+    expect(config).not.toHaveProperty('apiToken')
+    expect(JSON.stringify(config)).not.toContain('secret-token-value')
+  })
+
+  test('keeps the config on an __UNCHANGED__ token update (no rotation required)', async ({ page }) => {
+    await page.request.put(ENDPOINT, {
+      data: { isEnabled: true, apiToken: 'secret-token-value', baseUrl: 'https://api.shipsgo.com/v2' },
+    })
+
+    const update = await page.request.put(ENDPOINT, {
+      data: { isEnabled: false, apiToken: '__UNCHANGED__', baseUrl: 'https://api.shipsgo.com/v2' },
+    })
+    expect(update.ok()).toBeTruthy()
+
+    const config = await getConfig(page.request)
+    expect(config).not.toBeNull()
+    expect(config!.isEnabled).toBe(false)
+    expect(config).not.toHaveProperty('apiToken')
+  })
+
+  test('deletes the config; a subsequent GET returns null', async ({ page }) => {
+    await page.request.put(ENDPOINT, {
+      data: { isEnabled: true, apiToken: 'secret-token-value', baseUrl: 'https://api.shipsgo.com/v2' },
+    })
+    expect(await getConfig(page.request)).not.toBeNull()
+
+    const del = await page.request.delete(ENDPOINT)
+    expect(del.ok()).toBeTruthy()
+
+    expect(await getConfig(page.request)).toBeNull()
+  })
+})

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

@@ -0,0 +1,4 @@
+export const integrationMeta = {
+  description: 'Shipment-tracking integration coverage (ShipsGo fallback + config)',
+  dependsOnModules: ['shipment_tracking'],
+}