Skip to main content

openroam 0.1.0-rc.4 copy "openroam: ^0.1.0-rc.4" to clipboard
openroam: ^0.1.0-rc.4 copied to clipboard

retracted

Official OpenRoam Partner API client: eSIMs, airtime, utility payments, gift cards, hotels and flights.

OpenRoam SDK for Dart #

Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights. For servers and tools (never ship your API key inside a mobile or web app).

Install #

dart pub add openroam:0.1.0-rc.4

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 'package:openroam/openroam.dart';

final openroam = OpenRoam('your-key'); // or OpenRoam.fromEnvironment() with OPENROAM_API_KEY set

final found = await openroam.esims.search(countryCode: 'JP');
final body = EsimOrderRequest(currency: 'USD', items: [EsimOrderRequestItem(publicId: offerId)]);
final quote = await openroam.esims.quote(body);
final order = await openroam.esims.order(body);

await openroam.esims.getUsage(iccid);
openroam.close(); // when you no longer need the client

Every product is a field 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 (the request model itself) the next one, and query parameters are named arguments. A body the API does not require is nullable: pass null to send none.

Options when you need them:

final openroam = OpenRoam(
  'your-key',
  environment: OpenRoamEnvironment.sandbox, // default OpenRoamEnvironment.production
  maxRetries: 3,                            // default 0: no retries
  // baseUrl: 'https://...' to point anywhere else, for example a development host
  // httpClient: your own http.Client
);

OpenRoam.fromEnvironment(...) takes the same options and reads the key from OPENROAM_API_KEY.

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 OpenRoamException with the error body of the API: status, code (branch on this), errorName (the API's name, for example PRICE_ABOVE_LIMIT), message, requestId (keep it for support) and details. When no answer arrived (network error), status is null and cause has the original error. A call stopped through its abortTrigger throws the RequestAbortedException of package:http.

try {
  await openroam.esims.order(body);
} on OpenRoamException catch (error) {
  if (error.code == 11002) { /* the price rose above your maxPrice */ }
  else rethrow;
}

Lists and pages #

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

Webhooks #

verifyWebhook(
  secret: secret,
  timestamp: headers['x-openroam-timestamp']!,
  eventId: headers['x-openroam-event-id']!,
  signature: headers['x-openroam-signature']!,
  rawBody: rawBody, // exactly as received
); // throws WebhookSignatureException when invalid or older than 5 minutes

Order items and webhook items #

An order item (and a webhook item, and an item of an order request) holds one product variant, chosen by productType. Read it with the getter for its product, which is null for the others:

for (final item in order.items) {
  final esim = item.esim;
  if (esim != null) print(esim.fulfillment); // eSIM details are kept
}

The variants are airtime, esim, flight, giftCard, hotel and utility; item.value is the variant itself. An unknown productType throws a FormatException, never a silent gap.

Retries #

Retries are off by default. Set maxRetries to retry network errors, 429 and 502/503/504 with backoff, and to wait for a purchase that is still running (12002). A POST is sent again only with its Idempotency-Key, the same key and the same body, and order() always has one; a 500 never is.

final openroam = OpenRoam(apiKey, maxRetries: 3);

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

Good to know #

  • Amounts are { amount, currency }. price is what OpenRoam charges you, value what 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.

0
likes
0
points
726
downloads

Publisher

verified publisheropenroam.com

Weekly Downloads

Official OpenRoam Partner API client: eSIMs, airtime, utility payments, gift cards, hotels and flights.

Homepage

License

unknown (license)

Dependencies

collection, crypto, http, intl, meta

More

Packages that depend on openroam