@hoplynk/sdk

Official JavaScript/TypeScript SDK for the Hoplynk API.

Stream live GPS and telemetry from Starlink-connected vehicles — no direct network access to the vehicle required.

Install

npm install @hoplynk/sdk

Quickstart

import { HoplynkClient } from '@hoplynk/sdk'

const client = new HoplynkClient({
  apiKey: process.env.HOPLYNK_API_KEY, // hlk_...
})

Get an API key from the Hoplynk dashboard. Keys are prefixed hlk_ and are only shown once — store them in your environment.

REST API

List assets in a kit

const { assets } = await client.getAssets(kitId)
// assets: [{ id, name, type, status, whep_url?, ... }]

Get latest GPS fix

const loc = await client.getLocation(kitId, assetId)
if (loc) {
  console.log(loc.lat, loc.lon, loc.source) // e.g. 'starlink'
}

Get full telemetry snapshot

const telem = await client.getTelemetry(kitId, assetId)
// telem.gps   → GpsPayload
// telem.status → StatusPayload (Starlink link health)

Get Starlink link status

const status = await client.getStatus(kitId, assetId)
if (status) {
  console.log(status.downlink_mbps, status.uplink_mbps)
}

WebSocket streaming

For live updates, open a stream instead of polling:

const stream = client.stream({
  kitId,
  assetId,
  feeds: ['gps', 'status'], // default: ['gps']
  interval: 1,              // server push interval in seconds (0.5–10)
})

stream.on('ready', ({ feeds }) => {
  console.log('streaming', feeds)
})

stream.on('data', ({ feed, payload, ts }) => {
  if (feed === 'gps') {
    const { lat, lon, source, stale } = payload
    myMap.setCenter([lon, lat])
  }
  if (feed === 'status') {
    console.log('downlink:', payload.downlink_mbps, 'Mbps')
  }
})

stream.on('error', ({ message }) => {
  console.error('stream error:', message)
})

stream.on('close', ({ code }) => {
  // stream auto-reconnects unless you called stream.close()
})

// Stop streaming:
stream.close()

The WebSocket authenticates via a first-message handshake (API key never appears in the URL or server logs).

TypeScript types

import type {
  GpsPayload,
  StatusPayload,
  TelemetrySnapshot,
  StreamEvent,
} from '@hoplynk/sdk'

GpsPayload

| Field | Type | Description | |---|---|---| | lat | number | Latitude (degrees) | | lon | number | Longitude (degrees) | | alt_m | number \| null | Altitude (meters, WGS-84) | | accuracy_m | number \| null | Horizontal accuracy (meters) | | source | string | 'starlink' | 'starlink_cached' | 'cellular' | 'manual' | | stale | boolean | True if GPS fix is older than 30s | | timestamp | string | ISO 8601 UTC |

StatusPayload

| Field | Type | Description | |---|---|---| | state | string | Starlink dish state | | downlink_mbps | number | Download throughput | | uplink_mbps | number | Upload throughput | | pop_ping_latency_ms | number | Latency to Starlink POP | | pop_ping_drop_rate | number | Packet drop rate (0–1) | | obstruction_pct | number | Sky obstruction percentage | | alerts | string[] | Active Starlink alerts |

Environment variables

| Variable | Description | |---|---| | HOPLYNK_API_KEY | Your hlk_* API key |

IDs

You'll need a Kit ID and Asset ID for each vehicle. Find them in the Hoplynk dashboard, or call client.getAssets(kitId) to list assets programmatically.

License

MIT