@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 in meta.
• 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.