@enfinitos/sdk-maritime
EnfinitOS reference SDK for the MARITIME substrate.
This is an adapter-mostly SDK: a thin operator-side wrapper that sits between cruise-line IPTV middleware (Tripleplay / GuestCast), port-side IALA VTS display networks, and maritime satcom uplink shims (Inmarsat Fleet Xpress / Iridium Certus) and the EnfinitOS platform's resolve, proof-of-play, and health pipelines.
Architecture
┌──────────────────────────────────────────┐
│ EnfinitOSMaritimeClient │
│ (ts-core/src/maritimeClient.ts) │
│ │
│ ┌────────────────────────────────────┐ │
│ │ EnfinitOSRendererClient │ │
│ └────────────────────────────────────┘ │
│ ┌────────────────────────────────────┐ │
│ │ VesselSessionManager │ │
│ │ (cabin → pseudonym registry) │ │
│ └────────────────────────────────────┘ │
│ ┌────────────────────────────────────┐ │
│ │ MaritimeProofReporter │ │
│ │ (vessel-state envelope on every │ │
│ │ PlayEvent) │ │
│ └────────────────────────────────────┘ │
└────────────────┬─────────────────────────┘
│ attach(adapter)
┌────────────────▼─────────────────────────┐
│ MaritimeAdapter (interface) │
└─┬─────────────┬─────────────┬────────────┘
│ │ │
┌────▼──────┐ ┌────▼─────┐ ┌────▼─────────────┐
│Tripleplay │ │ GuestCast │ │ IALA VTS │
│ (Cisco) │ │ │ │ (port displays) │
└───────────┘ └───────────┘ └──────────────────┘
┌──────────────────┐
│ Inmarsat │
│ Fleet Xpress shim│
│ (no-render: link │
│ state + NMEA) │
└──────────────────┘2026 platform reality
Cruise-ship signage
- Princess MedallionClass (Carnival Corp / Princess Cruises) and Excalibur RFID (Royal Caribbean) drive the two flagship on-board IPTV + IPS-display networks. Both run on Linux-based digital-signage controllers + IPTV middleware.
- Tripleplay (Cisco-acquired 2020) and GuestCast are the two dominant middleware vendors. The SDK ships an adapter for each.
- Surfaces: cabin TV (IPTV) + stateroom-door OLED strips (IPS displays). RFID/Medallion taps surface as interaction events.
Port-side signage
- Vessel Traffic Services (VTS) display networks at port operations centres. IALA-compliant under G1110 (VTS Display Standards) + V-128 (service portfolio).
- The SDK ships an IALA-style REST adapter at
/iala/v1/....
Maritime satcom uplink
- Inmarsat Fleet Xpress — dual-band Ka (GX) primary + L (FleetBroadband) fallback. The mainstream 2026 choice.
- Iridium Certus — global L-band, especially high latitudes. Same operator-side interface as Fleet Xpress; the SDK does not ship a separate adapter.
- The shim parses NMEA 0183 GPRMC/GNRMC sentences for vessel state and pushes link state into the renderer-core health pipeline.
GMDSS safety guardrails
- GMDSS (Global Maritime Distress and Safety System) — mandatory for SOLAS-class vessels under SOLAS Chapter IV. The SDK explicitly refuses to route content through any GMDSS-reserved surface id (GMDSS\, DSC\, EPIRB\, SART\, VHF-CH16\, VHF-CH70\, 406MHZ\*). These frequencies carry voice + Morse safety + distress traffic and are NOT advertising substrates.
- The SDK does NOT speak analog GMDSS HF / MF channels.
Platform-side endpoints
POST /runtime/resolve— existing. Carries the vessel IMO, territory ISO, UNLOCODE, and surface type into the platform's targeting engine.POST /runtime/event-ingest— existing. Per-surface impression + interaction events ride this with the vessel envelope inmeta.POST /runtime/health-ingest— existing. Vessel-state + uplink-state heartbeats roll up here.
Getting started
import {
EnfinitOSMaritimeClient,
type SurfaceRef,
type VesselState,
} from "@enfinitos/sdk-maritime";
import { GuestCastAdapter } from "@enfinitos/sdk-maritime-cruise-iptv";
import { InmarsatFleetXpressAdapter } from "@enfinitos/sdk-maritime-inmarsat-fleet-xpress";
const client = new EnfinitOSMaritimeClient({
apiBaseUrl: "https://api.enfinitos.com",
vesselImo: "9614036",
operatorRef: "Royal Caribbean Group",
vesselName: "Symphony of the Seas",
authToken: process.env.ENFINITOS_TOKEN!,
});
await client.start();
// Plug in the IPTV adapter
const guestcast = new GuestCastAdapter({
baseUrl: "https://gc.cabin-server.local",
adapterId: "gc-1",
auth: { jwt: process.env.GUESTCAST_JWT! },
});
await client.attach(guestcast);
// Plug in the satcom shim — note: only one adapter is attached at a
// time; production deployments wire the vessel-state shim through
// the same adapter slot or via an event-stream multiplexer.
const fleetXpress = new InmarsatFleetXpressAdapter({
terminalUrl: "https://fx.local",
adapterId: "fx-1",
authToken: process.env.FLEETXPRESS_TOKEN!,
});
// Per-surface fetch + report
const surface: SurfaceRef = {
surfaceType: "IPS_DISPLAY",
surfaceId: "door-12A-405",
cabinNumber: "12A-405",
cabinClass: "BALCONY",
};
const asset = await client.fetchAdSlot({
cabinClass: "BALCONY",
cabinNumber: "12A-405",
surfaceType: "IPS_DISPLAY",
});
if (asset) {
await client.reportImpression(surface, asset);
}Honest scope
The SDK is intentionally narrow:
Does translate cruise-IPTV + VTS surface state into EnfinitOS proof events with a vessel-context envelope; track per-cabin pseudonyms for cross-surface attribution; surface uplink + vessel state into the platform's territorial-water targeting; enforce GMDSS distress-channel guardrails.
Does NOT touch GMDSS distress channels (refuses by surface-id pattern); render IPTV / IPS displays directly (the cabin-server middleware owns rendering); validate IMO numbers against the IMO registry (loose syntax check only); replace the vessel's bridge GMDSS HF / MF stack.