TypeScript SDK for the PingPoint Agent API — create freight loads, read live GPS positions, update statuses and confirm deliveries from your own software or AI agent.

Auth is a single sup_agent_… key issued from the PingPoint cabinet (Integrations → Agent API); it identifies your broker account and bills your prepaid balance. Load creation costs $0.65, a position read $0.02, status updates and delivery confirmations are free.

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: "+15551234567", // 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	Price
`createLoad(input, {idempotencyKey?})`	Create a load, get tracking + driver links	$0.65
`getPosition(loadNumber)`	Status, GPS track, stop timeline, on-time flag	$0.02
`updateStatus(loadNumber, status)`	`PLANNED` \| `AT_PICKUP` \| `IN_TRANSIT` \| `DELIVERED` \| `CANCELLED`	free
`confirmDelivery(loadNumber, {bolReceivedAt?})`	BOL received → load DELIVERED	free
`getPricing()`	Current USD price list	free
`getBalance()`	Prepaid balance, USD	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; 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.