OpenSpec Change: enterprise-api-plugin-port-tracking

Change ID: enterprise-api-plugin-port-tracking
Package: @suaveplan/api-plugin-port-tracking
Category: api/logistics
Target path: api/logistics/api-plugin-port-tracking
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-port-tracking.md

Summary

Deliver @suaveplan/api-plugin-port-tracking on the genesis branch from scratch at enterprise quality. Maritime port and vessel tracking plugin: vessel position (AIS data ingestion via pluggable AisAdapter), port arrival/departure tracking, berth scheduling, cargo manifest management, estimated-time-of-arrival (ETA) calculations, and integration with @suaveplan/api-plugin-logistics for sea-freight shipment correlation. Routes under /port-tracking. Per-table SurrealQL. Events: port:vessel:arrived, port:vessel:departed, port:ais:update.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB
`@suaveplan/api-plugin-logistics` (`workspace:^`)	Shipment correlation
`@suaveplan/datetime` (`workspace:^`)	ETA calculations
`@suaveplan/events` (`workspace:^`)	Event bus
`@suaveplan/error` (`workspace:^`)	`PortTrackingError` hierarchy
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createPortTrackingPlugin(aisAdapter?: AisAdapter, config?: PortTrackingConfig): PluginDescriptor

interface AisAdapter {
  getVesselPosition(mmsi: string): Promise<VesselPosition>
  subscribePositionUpdates(mmsi: string, callback: (pos: VesselPosition) => void): () => void
}

// Routes: GET /port-tracking/vessels/:mmsi, GET /port-tracking/ports/:portCode,
//         GET /port-tracking/ports/:portCode/arrivals, GET /port-tracking/manifests/:id

Error codes

type PortTrackingErrorCode =
  | "PORT_VESSEL_NOT_FOUND"
  | "PORT_AIS_UNAVAILABLE"
  | "PORT_CODE_NOT_FOUND"
  | "PORT_BERTH_CONFLICT"

File layout

api/logistics/api-plugin-port-tracking/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (vessel, port, berth, arrival, cargo_manifest tables)
  src/
    index.ts  events.ts  types/  errors/
    adapters/ais.port.ts
    services/vessel/  services/port/  services/berth/  services/manifest/  services/eta/
    routes/port-tracking/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/api-plugin-logistics, @suaveplan/datetime.

2.8 KiB Raw Blame History