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).
npm install @openroam/sdk@0.1.0-rc.6This 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.
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
});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 });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;
}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.
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 minutesRetries 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.
-
Amounts are
{ amount, currency }.priceis what OpenRoam charges you,valuewhat your customer receives. - Full API documentation: https://openroam.com (partner portal). Support: support@openroam.com.
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.