OpenRoam SDK for TypeScript and JavaScript

Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights. Works on Node 18+, edge runtimes and browsers (never put your API key in a browser).

Install

npm install @openroam/sdk@0.1.0-rc.6

This is a release candidate: install it by its exact version, as above; a plain install does not pick it up. Before 1.0 the API can change between minor versions; every change is listed in the changelog.

Quick start

import { OpenRoam } from '@openroam/sdk';

const openroam = new OpenRoam(process.env.OPENROAM_API_KEY); // or new OpenRoam() with OPENROAM_API_KEY set

const found = await openroam.esims.search({ countryCode: 'JP' });
const quote = await openroam.esims.quote({ currency: 'USD', items });
const order = await openroam.esims.order({ currency: 'USD', items });

await openroam.esims.getUsage(iccid);
await openroam.hotels.search({ /* ... */ });

Every product is a property of the client: esims, airtime, utilities, giftCards, hotels, flights, plus orders, orderItems, wallets, currencies, countries and mobileNetworks. Buying always reads search, quote, order; get fetches one thing you own, list... returns many, everything else starts with a verb. A path id is the first argument, a body is passed as it is.

Options when you need them:

const openroam = new OpenRoam({
  apiKey: 'key',
  environment: 'sandbox', // default 'production'
  maxRetries: 3,          // default 0: no retries
  // baseUrl: 'https://...' to point anywhere else, for example a development host
});

Orders are safe to repeat

An idempotency key means: if the same request arrives twice, OpenRoam makes one order, not two. order() creates a key for you on every call. To stay safe even if your own program crashes and asks again, pass a UUID generated once and persisted for that purchase, for example your order id if it is a UUID:

await openroam.esims.order(body, { idempotencyKey: myOrderId });

Errors

A failed call throws an OpenRoamError with the error body of the API: status, code (branch on this), name, message, requestId (keep it for support) and details. When no answer arrived (network error), status is undefined and cause has the original error.

import { OpenRoam, OpenRoamError } from '@openroam/sdk';

try {
  await openroam.esims.order(body);
} catch (error) {
  if (error instanceof OpenRoamError && error.code === 11002) { /* the price rose above your maxPrice */ }
  else throw error;
}

Lists and pages

Pagination depends on the method. esims.search accepts page and limit and returns { items, pagination }, while orders.list returns { orders, pagination }. esims.listCatalog accepts cursor and limit and returns { items, nextCursor }; pass nextCursor as cursor to fetch the next page. Some lists, such as esims.listCompatibleDevices, return an unpaged array.

Webhooks

import { verifyWebhook } from '@openroam/sdk';

await verifyWebhook({
  secret: process.env.OPENROAM_WEBHOOK_SECRET!,
  timestamp: req.headers['x-openroam-timestamp'],
  eventId: req.headers['x-openroam-event-id'],
  signature: req.headers['x-openroam-signature'],
  rawBody, // the body exactly as received, before JSON parsing
}); // throws WebhookSignatureError when invalid or older than 5 minutes

Retries

Retries are off by default. Set maxRetries to retry network errors, 429, 502/503/504 and "still running" (12002) safely: a POST is sent again only with its Idempotency-Key, the same key and the same body, and order() always has one.

const openroam = new OpenRoam({ apiKey, maxRetries: 3 });

The full behaviour: Retries and idempotency. retryMiddleware and newIdempotencyKey are also exported if you build your own requests.

Good to know

The client is generated from the OpenRoam Partner API description, so it always matches the API; webhooks, retry and the errors are hand-written. MIT licensed.