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

The SDK ships as a single file rather than a package for now. It has no dependencies, so copying it in is genuinely all there is to it — and nothing it does is unavailable over plain HTTP.

Install#

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.ts

Works anywhere fetch exists: Node 18+, Deno, Bun, Cloudflare Workers, the browser — though not with a live key, which must never leave your server.

Initialise#

setup
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 itself

The 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.

Options
apiKeystringrequired
Must start with rk_test_ or rk_live_. The constructor throws otherwise, rather than failing later with a 401.
baseUrlstringoptional
Defaults to production. Override for local development.
timeoutMsnumberoptional
Per-request timeout. Default 20000.
maxRetriesnumberoptional
Retries for timeouts, 429 and 5xx. Default 2. A 4xx is never retried.
fetchtypeof fetchoptional
Your own fetch implementation — for instrumentation, proxying, or tests.

Methods#

MethodCallsReturns
quote(params)GET /quotePrice, distance, ETA and vehicle options.
createDelivery(params)POST /deliveriesThe created delivery, with tracking code and payment block.
getDelivery(idOrCode)GET /deliveries/{id}The delivery and its event timeline.
listDeliveries({ limit, before })GET /deliveriesA page, plus has_more and next_before.
cancelDelivery(idOrCode, reason?)POST /deliveries/{id}/cancelThe cancelled delivery.
usage
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.

errors
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, 429 and 5xx are retried with exponential backoff and jitter.
  • A 4xx is 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-out POST may 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#

options
// 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.