@suverselabs/pingpoint-sdk

@suverselabs/pingpoint-sdk

TypeScript SDK for live truck GPS tracking over the PingPoint Agent API: create a freight load, PingPoint texts the driver an app link (onboarding takes about a minute — no ELD provider, no corporate account, no annual contract), then read live position, GPS track, stop timeline and ETA, and confirm delivery from your own software or AI agent.

npm install @suverselabs/pingpoint-sdk

Quick start

import { PingPointAgent } from "@suverselabs/pingpoint-sdk";

const pp = new PingPointAgent({ apiKey: process.env.PINGPOINT_AGENT_KEY! });

const load = await pp.createLoad({
  driverPhone: "[phone]", // the driver app link is sent to this number
  pickups: [{ facilityName: "General Mills DC", address: "6492 Tower Lane", city: "Claremore", state: "OK", zip: "74017" }],
  deliveries: [{ address: "6499 Caldwell Park Dr", city: "Charlotte", state: "NC", zip: "28269" }],
});
console.log(load.loadNumber, load.trackingLink);

const pos = await pp.getPosition(load.loadNumber); // $0.02
console.log(pos.status, `${pos.pingCount} GPS points`);

Required on create: driverPhone (E.164) and the pickups / deliveries arrays — each stop needs address, city, state, zip. Everything else (shipperName, carrierName, equipmentType, customerRef, rate, miles, weight, truckNumber) is optional. A load may have several pickups and deliveries. customerRef doubles as a dedup key — re-sending it returns the existing load (deduplicated: true) instead of creating a duplicate.

Operations

Method	What it does	Returns	Price
createLoad(input, {idempotencyKey?})	Creates the load; driver gets the app link by SMS	loadNumber, public trackingLink, driver web/app links, dedup flag	$0.65
getPosition(loadNumber)	Live state of the load	status, GPS track (last 500 points), stops with arrive/depart timestamps, distance, on-time flag, dwell times, ETA block	$0.02
getTripStats(loadNumber)	Post-trip summary over the whole GPS trip (best on a DELIVERED load)	stats with distance, duration, avg/max speed, hard accel/brake counts, city/highway/parked/night shares, GPS coverage, first/last ping	$0.02
updateStatus(loadNumber, status)	Explicit status override — intentionally closed, see below	throws ApiError (HTTP 410, body.code: "STATUS_DOOR_CLOSED")	free
confirmDelivery(loadNumber, {bolReceivedAt?})	BOL received → load at its delivery stop flips to DELIVERED	{ ok, oldStatus, newStatus: "DELIVERED" }	free
getPricing()	Current USD price list	{ currency, prices }	free
getBalance()	Prepaid balance	{ currency, balanceUsd }	free

Why updateStatus answers 410. PingPoint drives load statuses itself, from driver GPS and geofence events — external status writes are closed on purpose, and the endpoint answers 410 STATUS_DOOR_CLOSED. Treat that as a data-integrity guarantee: a status you read was never hand-set by anyone; it is backed by actually recorded position.

Example — read a position

const pos = await pp.getPosition("LD-2026-042317");

{
  "loadNumber": "LD-2026-042317",
  "status": "IN_TRANSIT",
  "createdAt": "2026-08-18T14:02:11.000Z",
  "deliveredAt": null,
  "distanceMiles": 412.7,
  "onTime": null,
  "delayMinutes": null,
  "pickupDwellMinutes": 38,
  "deliveryDwellMinutes": null,
  "stops": [
    { "type": "PICKUP", "sequence": 1, "city": "Claremore", "state": "OK",
      "windowFrom": "2026-08-18T15:00:00.000Z", "windowTo": "2026-08-18T19:00:00.000Z",
      "arrivedAt": "2026-08-18T15:47:31.000Z", "departedAt": "2026-08-18T16:25:09.000Z" },
    { "type": "DELIVERY", "sequence": 2, "city": "Charlotte", "state": "NC",
      "windowFrom": "2026-08-20T12:00:00.000Z", "windowTo": "2026-08-20T16:00:00.000Z",
      "arrivedAt": null, "departedAt": null }
  ],
  "gpsTrack": [
    { "lat": 36.3126, "lng": -95.6161, "speed": null, "heading": null, "ts": "2026-08-18T16:25:09.000Z" }
  ],
  "pingCount": 214,
  "eta": {
    "nextStop": { "type": "DELIVERY", "sequence": 2, "city": "Charlotte", "state": "NC" },
    "receivingWindow": { "from": "2026-08-20T12:00:00.000Z", "to": "2026-08-20T16:00:00.000Z" },
    "distanceToNextStopMi": 611.4,
    "driveTimeHours": 11.2,
    "moving": true,
    "stoppedForMinutes": null,
    "etaWindow": { "from": "2026-08-20T13:05:00.000Z", "to": "2026-08-20T15:40:00.000Z" },
    "tracking": { "state": "pinging", "noDataForMinutes": null },
    "reason": null
  }
}

(gpsTrack shortened; the API returns up to the last 500 points.)

Example — trip summary stats

Once the load is DELIVERED (works mid-trip too — returns the trip so far):

const trip = await pp.getTripStats("LD-2026-648319"); // $0.02

{
  "loadNumber": "LD-2026-648319",
  "loadId": "927741bc-dfd0-41ba-9e99-5c5031c756f9",
  "stats": {
    "dataPoints": 4785,
    "durationSeconds": 69329,
    "estimatedDistanceMiles": 486.591,
    "avgSpeedMph": 25.27,
    "maxSpeedMph": 88.22,
    "hardAccelCount": 280,
    "hardBrakeCount": 168,
    "cityMilesPct": 9.96,
    "highwayMilesPct": 88.65,
    "parkedTimePct": 53.65,
    "nightPct": 44.7,
    "coveragePct": 100,
    "firstAt": "2026-08-18T16:53:25.000Z",
    "lastAt": "2026-08-19T12:08:54.000Z"
  }
}

Distances are miles, speeds are mph, percentages are 0–100, timestamps are UTC. getPosition answers "where is the truck now"; getTripStats answers "how did the trip go".

Getting a key

• Sign up at pingpoint.suverse.io (e-mail or Google/GitHub).
• Cabinet → Integrations → Agent API → Issue key.
• The sup_agent_… key arrives by e-mail; PingPoint never stores the secret. Lost it — re-issue from the same page.

Free operations work at zero balance. Paid ones debit your prepaid balance (cabinet → Billing); when it can't cover a call you get a typed 402 and nothing is charged.

Pricing

Operation	Price
Create a load	$0.65
Read load position	$0.02 per request
Trip summary stats	$0.02 per request
Status update / delivery confirm / pricing / balance	free

Errors

Every failure is a typed error (all extend PingPointAgentError with .status and the raw .body):

InsufficientFundsError (402 — top up in the cabinet; carries balanceUsd/priceUsd), MissingFieldsError (400, .fields lists what's missing), InvalidDriverPhoneError, UnknownBrokerError (422), ForbiddenError (403 — not your load), NotFoundError (404), DeliveryNotReadyError (422 — the driver hasn't arrived; don't retry, delivery completes automatically on arrival), BillingUnavailableError (503 — nothing charged, retry later), ApiError (everything else, including the intentional 410 STATUS_DOOR_CLOSED from updateStatus; status: 0 = network failure).

Retries

Pass the same idempotencyKey when retrying createLoad — the balance is debited and the load created at most once:

await pp.createLoad(input, { idempotencyKey: "order-483920" });

Options

new PingPointAgent({
  apiKey: "sup_agent_…",           // required
  baseUrl: "https://api.suverse.io", // default
  fetch: customFetch,               // optional (tests/instrumentation)
});

Node ≥ 18 (uses global fetch). Zero runtime dependencies.

MCP server for AI agents: @suverselabs/pingpoint-mcp.

Full API documentation: https://pingpoint.suverse.io/docs