Skip to content

sdk.md

Latest commit

 

History

History
110 lines (72 loc) · 5.08 KB

sdk.md

File metadata and controls

110 lines (72 loc) · 5.08 KB
Raw

SDK reference — @suverselabs/pingpoint-sdk

Typed client for the PingPoint Agent API (https://api.suverse.io/v1/agent/*). Node ≥ 18 (global fetch), ESM + CJS, zero runtime dependencies.

npm install @suverselabs/pingpoint-sdk

Constructor

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

const pp = new PingPointAgent({
  apiKey: "sup_agent_…",              // required — issued in the cabinet, Integrations → Agent API
  baseUrl: "https://api.suverse.io",  // optional, default shown
  fetch: customFetch,                 // optional — tests / instrumentation
});

Throws synchronously when apiKey is missing or global fetch is unavailable.

Methods

createLoad(input, options?) — $0.65

createLoad(input: CreateLoadInput, options?: { idempotencyKey?: string }): Promise<CreateLoadResult>

Creates a freight load; PingPoint texts the driver link to input.driverPhone. Required: driverPhone (E.164) and pickups / deliveries (each stop: address, city, state, zip). Optional: shipperName, carrierName, equipmentType, customerRef (dedup key), rate, miles, weight, truckNumber; per stop facilityName, date, lat+lng. Pass the same idempotencyKey on retries — the debit and the load happen at most once. Returns loadNumber, trackingLink, driverWebLink, driverAppLink, driverResolution ("bound" | "unresolved_truck" | "none"), and deduplicated: true when an existing load with the same customerRef was returned.

Throws: MissingFieldsError, InvalidDriverPhoneError, InsufficientFundsError, UnknownBrokerError, BillingUnavailableError.

getPosition(loadNumber) — $0.02

getPosition(loadNumber: string): Promise<LoadPosition>

Live state: status, gpsTrack (up to 500 points; mph / degrees / UTC), stops with geofence timestamps, distanceMiles, onTime, dwell minutes, pingCount, eta. Every call is billed — do not poll in a loop.

Throws: NotFoundError, ForbiddenError, InsufficientFundsError, UnknownBrokerError.

getTripStats(loadNumber) — $0.02

getTripStats(loadNumber: string): Promise<TripStatsResult>

Aggregated summary over every recorded ping — meant for a DELIVERED load; mid-trip returns the trip so far. stats fields and their definitions: tools/get_trip_stats.md.

Throws: NotFoundError, ForbiddenError, InsufficientFundsError, UnknownBrokerError.

cancelLoad(loadNumber) — free

cancelLoad(loadNumber: string): Promise<CancelLoadResult>

Cancels the load: status CANCELLED, tracking stops, further driver pings are refused. Nothing is deleted — stops and the GPS track recorded so far stay readable. No refund for what was already spent. Idempotent: a repeat call answers { ok: true, idempotent: true }.

Throws: LoadAlreadyDeliveredError (409 — delivered is final, don't retry), NotFoundError, ForbiddenError.

updateStatus(loadNumber, status) — not part of the API

updateStatus(loadNumber: string, status: LoadStatus): Promise<UpdateStatusResult>

Always throws ApiError with .status === 501 (body.code: "OPERATION_NOT_AVAILABLE"). Statuses advance automatically from GPS and geofence events; see tools/update_load_status.md.

getPricing() — free

getPricing(): Promise<Pricing>

Live USD price list (load_create, position_read, trip_stats, cancel, …). Never hardcode prices.

getBalance() — free

getBalance(): Promise<Balance>

Prepaid USD balance. A 402 on a paid call means nothing was charged.

On load creation the gateway wraps the body — the machine code arrives in upstreamCode and the original body in upstream. The SDK unwraps both shapes, so the typed errors above are the same either way.

Errors

Every non-2xx answer throws a subclass of PingPointAgentError with .status (HTTP status, 0 for transport failures) and .body (raw response body):

Error Status Extra fields Notes
MissingFieldsError 400 fields: string[] Dotted paths, e.g. pickups.0.zip.
InvalidDriverPhoneError 400 Phone not E.164.
InsufficientFundsError 402 balanceUsd?, priceUsd?, billingUrl? Nothing charged.
ForbiddenError 403 Load belongs to another account.
NotFoundError 404 No such load.
UnknownBrokerError 422 brokerEmail? Key's account not registered.
LoadAlreadyDeliveredError 409 loadStatus? Cancel on a delivered load. Don't retry.
TooManyStopsError 400 limits?, received? Over 2 pickups or 3 deliveries. Nothing created.
BillingUnavailableError 503 Nothing charged; retry later.
ApiError any other Includes the 501 from updateStatus; status: 0 = network failure.

Exported types

StopInput, CreateLoadInput, CreateLoadResult, DriverResolution, LoadStatus, LoadPosition, PositionStop, GpsPoint, TripStats, TripStatsResult, UpdateStatusResult, CancelLoadResult, Pricing, Balance, PingPointAgentOptions.