Tools
JavaScript SDK
A thin, dependency-free TypeScript client over the same endpoints. It handles what every integrator would otherwise get subtly wrong — the auth header, timeouts, typed errors, and retries that cannot duplicate a delivery — and gets out of the way otherwise.
Not on npm yet
Install#
# Not published to npm yet. One file, no dependencies —
# drop it into your project and import it directly.
curl -O https://developers.rider.rheochat.com/sdk/rheochat-dispatch.tsWorks anywhere fetch exists: Node 18+, Deno, Bun, Cloudflare Workers, the browser — though not with a live key, which must never leave your server.
Initialise#
import { RheoChatDispatch } from "./rheochat-dispatch";
const dispatch = new RheoChatDispatch({
apiKey: process.env.RHEOCHAT_API_KEY!, // rk_test_… or rk_live_…
// timeoutMs: 20_000,
// maxRetries: 2,
});
dispatch.environment; // "test" | "live", read from the key itselfThe environment is read from the key prefix rather than taken as a second argument. Two sources for one fact is two chances to disagree, and that disagreement would be silent: live traffic believed to be test.
apiKeystringrequiredrk_test_ or rk_live_. The constructor throws otherwise, rather than failing later with a 401.baseUrlstringoptionaltimeoutMsnumberoptional20000.maxRetriesnumberoptional429 and 5xx. Default 2. A 4xx is never retried.fetchtypeof fetchoptionalMethods#
| Method | Calls | Returns |
|---|---|---|
quote(params) | GET /quote | Price, distance, ETA and vehicle options. |
createDelivery(params) | POST /deliveries | The created delivery, with tracking code and payment block. |
getDelivery(idOrCode) | GET /deliveries/{id} | The delivery and its event timeline. |
listDeliveries({ limit, before }) | GET /deliveries | A page, plus has_more and next_before. |
cancelDelivery(idOrCode, reason?) | POST /deliveries/{id}/cancel | The cancelled delivery. |
import { RheoChatDispatch, withIdempotencyKey } from "./rheochat-dispatch";
const dispatch = new RheoChatDispatch({ apiKey: process.env.RHEOCHAT_API_KEY! });
// Quote
const quote = await dispatch.quote({
pickup: { lat: 9.8965, lng: 8.8583 },
dropoff: { lat: 9.9285, lng: 8.8921 },
weightKg: 2,
});
// Book
const delivery = await dispatch.createDelivery({
pickup: { name: "Mama Put Kitchen", phone: "+2348012345678",
address: "12 Ahmadu Bello Way, Jos", lat: 9.8965, lng: 8.8583 },
dropoff: { name: "Amaka O.", phone: "+2348098765432",
address: "5 Rwang Pam St, Jos", lat: 9.9285, lng: 8.8921 },
itemDescription: "Jollof rice x2",
weightKg: 2,
paymentMethod: "cod",
reference: order.id,
idempotencyKey: withIdempotencyKey(order.id),
});
// Track
const latest = await dispatch.getDelivery(delivery.tracking_code);
// List
const page = await dispatch.listDeliveries({ limit: 50 });
// Cancel
await dispatch.cancelDelivery(delivery.tracking_code, "Customer changed their mind");Errors#
Every failure — including a network one — throws RheoChatDispatchError. A network failure or timeout carries code network_error and status 0, so one catch handles both worlds.
import { RheoChatDispatchError } from "./rheochat-dispatch";
try {
await dispatch.createDelivery(params);
} catch (err) {
if (err instanceof RheoChatDispatchError) {
err.code; // "unprocessable" — branch on this
err.status; // 422
err.requestId; // quote this to support
err.details; // { status: "picked_up" }, { missing: [...] }, …
err.isRetryable; // 429 or 5xx
}
throw err;
}Retries#
- Timeouts,
429and5xxare retried with exponential backoff and jitter. - A
4xxis never retried — it will fail identically however many times it is sent. - A booking is only retried when you passed an
idempotencyKey. Without one, a timed-outPOSTmay already have created a delivery nobody saw the reply to, so the SDK fails fast rather than risking a second rider on your behalf.
withIdempotencyKey()
withIdempotencyKey(seed) returns the seed when you give it one, and a generated value otherwise. Give it your order id. A generated key is only safe if you store it before the first attempt — see Choosing a key.
Advanced#
// Bring your own fetch — a proxied agent, a Worker's fetch, a test double.
const dispatch = new RheoChatDispatch({
apiKey: process.env.RHEOCHAT_API_KEY!,
fetch: myInstrumentedFetch,
baseUrl: "http://localhost:4000", // local backend
timeoutMs: 30_000,
maxRetries: 3,
});Types#
The file exports Quote, Delivery, CreateDeliveryParams, QuoteParams, Party, Coordinates, Environment, ClientOptions and RheoChatDispatchError. They mirror the REST payloads exactly; nothing is renamed on the way through, so a field you read in the reference is the field you get in TypeScript.