@onesim.global/sdk 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,40 @@
1
+ # Changelog
2
+
3
+ The client follows [semantic versioning](https://semver.org). A minor release
4
+ adds what the API added (fields, endpoints, event types, error codes); a major
5
+ release would follow a new API version (`/v2`).
6
+
7
+ ## 0.1.0
8
+
9
+ The first release, for version 1 of the onesim partner API.
10
+
11
+ - `new OnesimClient()`, also the default export, with the key from
12
+ `ONESIM_API_KEY` or `apiKey`, and `baseURL`, `timeout` (per attempt),
13
+ `maxRetries` and `fetch`: your catalogue (`packages.list`,
14
+ `packages.retrieve`), orders (`orders.create`, `orders.createAndPoll`,
15
+ `orders.retrieve`, `orders.list`, `orders.listAll`, `orders.poll`), eSIMs
16
+ (`esims.retrieve`, `esims.list`, `esims.listAll`) and your balance
17
+ (`balance.retrieve`).
18
+ - `orders.create` sends one Idempotency-Key on every attempt, yours or a new
19
+ UUID, and puts it on any error it throws, so a purchase is never bought
20
+ twice.
21
+ - `orders.poll` follows a pending order (`202`) until it is completed or
22
+ failed; `orders.createAndPoll` creates the order and polls it, and resolves
23
+ with the final order, a failed one included.
24
+ - Retries with backoff when there is no answer and on `429` (after
25
+ `Retry-After`) and `5xx`; never on `provisioning_failed`,
26
+ `esims_unavailable` or another `4xx`. A timeout per attempt, and an
27
+ `AbortSignal` on every call.
28
+ - Errors as classes, all extending `OnesimError`: `APIError` with the API's
29
+ `code`, `requestId` and details, and its subclasses by status
30
+ (`BadRequestError`, `AuthenticationError`, `PermissionDeniedError`,
31
+ `NotFoundError`, `ConflictError`, `RateLimitError`,
32
+ `InternalServerError`); `APIConnectionError` and
33
+ `APIConnectionTimeoutError`; `PollTimeoutError`;
34
+ `WebhookVerificationError`.
35
+ - `verifyWebhook` checks the `Onesim-Signature` header and returns the event,
36
+ typed by its `type`.
37
+ - Types for every request, response and event, generated from the API's
38
+ contract, with its field names.
39
+ - No dependencies. ES modules and CommonJS. Node.js 20 or later, Deno, Bun and
40
+ Cloudflare Workers.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Horizon Digital Ventures, LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,366 @@
1
- # Temporary Holding Version
1
+ # onesim partner API for TypeScript
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The TypeScript client for the onesim partner API. Your servers use it to buy
4
+ blank eSIMs, data packages and bundles from your partner balance, to read your
5
+ catalogue, orders and eSIMs, and to verify webhooks.
6
+
7
+ Its types come from the API's contract. Field names are the API's own
8
+ (`esim_price`, `next_cursor`, `activation_code`): what the reference at
9
+ <https://api.onesim.global/docs> shows is what you get. Read the guide there
10
+ first; this page covers the SDK.
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ npm install @onesim.global/sdk
16
+ # or
17
+ pnpm add @onesim.global/sdk
18
+ # or
19
+ yarn add @onesim.global/sdk
20
+ ```
21
+
22
+ It has no dependencies and runs on Node.js 20 or later, Deno, Bun and
23
+ Cloudflare Workers. It ships as an ES module and as CommonJS:
24
+
25
+ ```js
26
+ const { OnesimClient } = require('@onesim.global/sdk');
27
+ ```
28
+
29
+ ## Quick start
30
+
31
+ ```ts
32
+ import OnesimClient from '@onesim.global/sdk';
33
+
34
+ const onesim = new OnesimClient(); // reads ONESIM_API_KEY
35
+
36
+ const catalogue = await onesim.packages.list(); // your packages and prices
37
+ const balance = await onesim.balance.retrieve(); // balance.available: cents to spend
38
+ ```
39
+
40
+ The client reads your key from the `ONESIM_API_KEY` environment variable, or
41
+ takes it as `new OnesimClient({ apiKey })`. `OnesimClient` is also a named
42
+ export.
43
+
44
+ Your key is a secret for your servers only. Never put it in an app, a browser
45
+ or a URL. Every key is live: what it buys is real and paid from your balance.
46
+
47
+ ## Buying
48
+
49
+ | `type` | You get | You pay |
50
+ | --------- | ---------------------------------------------------- | ----------------------- |
51
+ | `esim` | A blank eSIM with its activation code, no data. | `catalogue.esim_price` |
52
+ | `package` | A package on an eSIM you own: the first or a top-up. | the package's `price` |
53
+ | `bundle` | A new eSIM with the package already on it. | `package.bundle.amount` |
54
+
55
+ A `null` price means "not offered that way". Amounts are in cents of your
56
+ account's currency. Pass `expected_amount`, the price you showed your customer:
57
+ if the price has changed since, the order is refused with `price_changed` and
58
+ nothing is charged.
59
+
60
+ ```ts
61
+ const order = await onesim.orders.createAndPoll(
62
+ {
63
+ type: 'bundle',
64
+ package_id: pkg.id,
65
+ reference: booking.id,
66
+ expected_amount: pkg.bundle!.amount
67
+ },
68
+ { idempotencyKey: booking.orderKey }
69
+ );
70
+
71
+ if (order.status === 'completed') {
72
+ // order.esim.activation_code for the QR code, order.esim.ios_install_url,
73
+ // order.esim.android_install_url
74
+ } else {
75
+ // failed: the amount is already back on your balance
76
+ }
77
+ ```
78
+
79
+ ### Idempotency keys
80
+
81
+ Every purchase needs its own key, a UUID. The SDK sends the same key on every
82
+ retry it makes, so one call never buys twice.
83
+
84
+ Make the key yourself, store it with your booking before you call, and pass it
85
+ as `idempotencyKey`. If your process crashes or the call throws, call `create`
86
+ (or `createAndPoll`) again with the same key and body: you get the same order,
87
+ charged once.
88
+
89
+ ```ts
90
+ booking.orderKey ??= crypto.randomUUID();
91
+ await saveBooking(booking);
92
+ const order = await onesim.orders.create(body, {
93
+ idempotencyKey: booking.orderKey
94
+ });
95
+ ```
96
+
97
+ Without a key, the SDK makes a new one for each call. An error thrown by
98
+ `create` or `createAndPoll` carries the key it used as `error.idempotencyKey`.
99
+
100
+ The same key with a different body is refused with `idempotency_conflict`. A
101
+ `502 provisioning_failed` is final: that order failed and was refunded, and
102
+ buying again needs a new key.
103
+
104
+ ### Polling
105
+
106
+ `create` answers at once when the order is complete. When the network provider
107
+ has not confirmed yet, the order comes back with `status: 'pending'`. It
108
+ completes or fails within about ten minutes.
109
+
110
+ `orders.create` never waits: it returns the order as the API answers it,
111
+ pending or not. Follow a pending order with `orders.poll`, or with the
112
+ `order.completed` and `order.failed` webhooks:
113
+
114
+ ```ts
115
+ const final = await onesim.orders.poll(order.id); // every 3 s, for up to 11 minutes
116
+ ```
117
+
118
+ `orders.poll` resolves with the order once it is `completed`, `failed` or
119
+ `refunded`. Its `timeout` (milliseconds, default 660 000) bounds the whole
120
+ poll, slow reads and their retries included; `pollInterval` (default 3 000) is
121
+ the pause between reads. If time runs out first, it throws `PollTimeoutError`,
122
+ whose `order` is the order as last read (absent only if no read answered in
123
+ time).
124
+
125
+ `orders.createAndPoll` does both: it creates the order, polls it while it is
126
+ pending, and resolves with the final order, whatever its status. A failed
127
+ order does not throw here: `502 provisioning_failed` resolves with the failed
128
+ order. So check `order.status`. Other errors still throw. It takes
129
+ `idempotencyKey`, `timeout` and `pollInterval`.
130
+
131
+ ## Errors
132
+
133
+ Every error the SDK throws for the API extends `OnesimError`.
134
+
135
+ An answer with an error status is an `APIError`, or a subclass named after its
136
+ status:
137
+
138
+ | Status | Class | Codes |
139
+ | ------ | ----------------------- | ------------------------------------------------------------------------------------------- |
140
+ | 400 | `BadRequestError` | `invalid_request`, `idempotency_key_required` |
141
+ | 401 | `AuthenticationError` | `unauthorized` |
142
+ | 403 | `PermissionDeniedError` | `not_offered` |
143
+ | 404 | `NotFoundError` | `not_found` |
144
+ | 409 | `ConflictError` | `idempotency_conflict`, `esim_busy`, `price_changed`, `esim_limit_reached`, `esim_unusable` |
145
+ | 429 | `RateLimitError` | `rate_limited` |
146
+ | 5xx | `InternalServerError` | `internal_error`, `provisioning_failed`, `esims_unavailable` |
147
+ | other | `APIError` | e.g. 402 `insufficient_balance` |
148
+
149
+ The other errors:
150
+
151
+ | Class | When |
152
+ | --------------------------- | ------------------------------------------------------------------------- |
153
+ | `APIConnectionError` | No answer after every retry: the network failed or the attempt timed out. |
154
+ | `APIConnectionTimeoutError` | An `APIConnectionError` whose last attempt ran out of `timeout`. |
155
+ | `PollTimeoutError` | Polling ran out of time; `error.order` is still pending. |
156
+ | `WebhookVerificationError` | A webhook delivery failed verification. |
157
+
158
+ After an `APIConnectionError` from `create` you cannot know whether the order
159
+ was placed: call `create` again with the same key and body, and you get the
160
+ order, paid for once.
161
+
162
+ Act on `error.code`; `error.message` is for people and may change. Quote
163
+ `error.requestId` when you contact us. New codes may be added: handle a code
164
+ you do not know by `error.status`. `code` is `null` when the answer was not
165
+ the API's (an HTML page from a proxy, say).
166
+
167
+ ```ts
168
+ import { APIError, ConflictError } from '@onesim.global/sdk';
169
+
170
+ try {
171
+ await onesim.orders.create(body, { idempotencyKey });
172
+ } catch (error) {
173
+ if (error instanceof ConflictError && error.code === 'price_changed') {
174
+ // error.amount is the current amount
175
+ } else if (error instanceof APIError) {
176
+ switch (error.code) {
177
+ case 'insufficient_balance':
178
+ // top up your balance
179
+ break;
180
+ case 'esim_limit_reached':
181
+ // error.limit is 'blank' or 'daily'
182
+ break;
183
+ default:
184
+ console.error(error.status, error.code, error.requestId);
185
+ }
186
+ } else {
187
+ throw error;
188
+ }
189
+ }
190
+ ```
191
+
192
+ The codes and their meaning are in the guide, under "Errors".
193
+
194
+ ## Paging
195
+
196
+ `orders.list` and `esims.list` return one page as the API sends it:
197
+ `{ data, next_cursor }`, newest first. Pass `next_cursor` as `cursor` for the
198
+ next page; it is `null` on the last one.
199
+
200
+ `orders.listAll` and `esims.listAll` follow the pages for you:
201
+
202
+ ```ts
203
+ for await (const order of onesim.orders.listAll({
204
+ created_after: new Date('2026-11-01')
205
+ })) {
206
+ console.log(order.id, order.status);
207
+ }
208
+ ```
209
+
210
+ `created_after` takes a `Date` or an ISO string. The orders filters are
211
+ `esim_id`, `reference` and `created_after`; the eSIMs filter is `iccid`.
212
+
213
+ ## Webhooks
214
+
215
+ `verifyWebhook` checks the `Onesim-Signature` header against your endpoint's
216
+ signing secret (`whsec_…`) and the delivery's age, then returns the event. It
217
+ needs no API key.
218
+
219
+ It needs the raw body, exactly as received. Parsed and re-serialised JSON has
220
+ other bytes, and its signature does not match.
221
+
222
+ With Express:
223
+
224
+ ```ts
225
+ import express from 'express';
226
+ import { WebhookVerificationError, verifyWebhook } from '@onesim.global/sdk';
227
+
228
+ const app = express();
229
+
230
+ app.post(
231
+ '/onesim/webhooks',
232
+ express.raw({ type: 'application/json' }),
233
+ async (req, res) => {
234
+ let event;
235
+ try {
236
+ event = await verifyWebhook({
237
+ payload: req.body, // a Buffer, thanks to express.raw
238
+ signature: req.get('onesim-signature'),
239
+ secret: process.env.ONESIM_WEBHOOK_SECRET!
240
+ });
241
+ } catch (error) {
242
+ if (error instanceof WebhookVerificationError)
243
+ return res.status(400).send(error.reason);
244
+ throw error;
245
+ }
246
+ await handle(event);
247
+ res.sendStatus(204);
248
+ }
249
+ );
250
+ ```
251
+
252
+ With a fetch-style handler (Cloudflare Workers, Deno, Bun, Next.js route
253
+ handlers):
254
+
255
+ ```ts
256
+ export async function POST(request: Request): Promise<Response> {
257
+ let event;
258
+ try {
259
+ event = await verifyWebhook({
260
+ payload: await request.text(),
261
+ signature: request.headers.get('onesim-signature'),
262
+ secret: process.env.ONESIM_WEBHOOK_SECRET!
263
+ });
264
+ } catch (error) {
265
+ if (error instanceof WebhookVerificationError)
266
+ return new Response(error.reason, { status: 400 });
267
+ throw error;
268
+ }
269
+ await handle(event);
270
+ return new Response(null, { status: 204 });
271
+ }
272
+ ```
273
+
274
+ The event is typed by its `type`:
275
+
276
+ ```ts
277
+ import type { WebhookEvent } from '@onesim.global/sdk';
278
+
279
+ async function handle(event: WebhookEvent) {
280
+ switch (event.type) {
281
+ case 'order.completed':
282
+ case 'order.failed':
283
+ // event.data.id, event.data.status, event.data.reference
284
+ break;
285
+ case 'package.usage':
286
+ // event.data.percent_used
287
+ break;
288
+ default:
289
+ // We add event types without notice: ignore one you do not know.
290
+ }
291
+ }
292
+ ```
293
+
294
+ Answer with any `2xx` within 10 seconds. Anything else is retried, seven times
295
+ over about two days.
296
+ Delivery is at least once and in no particular order: ignore an event `id` you
297
+ have seen, and read the order or eSIM when order matters.
298
+
299
+ A delivery more than five minutes old or ahead is refused
300
+ (`timestamp_out_of_tolerance`); `toleranceSeconds` changes that. A header may
301
+ carry more than one `v1` signature; any match is accepted.
302
+
303
+ ## Configuration
304
+
305
+ ```ts
306
+ const onesim = new OnesimClient({
307
+ apiKey: 'osk_live_…', // default: process.env.ONESIM_API_KEY
308
+ baseURL: 'https://api.onesim.global', // the default
309
+ timeout: 60_000, // per attempt, in milliseconds
310
+ maxRetries: 2,
311
+ fetch // another fetch, e.g. a test double
312
+ });
313
+ ```
314
+
315
+ The options' types are exported: `ClientOptions`, `RequestOptions`,
316
+ `CreateOrderOptions` and `PollOptions`.
317
+
318
+ ## Retries and timeouts
319
+
320
+ Each attempt may take `timeout` milliseconds (default 60 000: placing an order
321
+ can make two calls of up to 20 seconds each to the network provider). A failed
322
+ attempt is retried up to `maxRetries` times (default 2), after a pause that
323
+ grows from about half a second to at most 8 seconds, with jitter.
324
+
325
+ | Retried | Not retried |
326
+ | --------------------------------------------- | ---------------------------------- |
327
+ | No answer: a network error or a timeout | Any other `4xx` |
328
+ | `429`, after its `Retry-After` (at most 60 s) | `502 provisioning_failed`: final |
329
+ | `500`, `502`, `503`, `504` | `503 esims_unavailable`: try later |
330
+
331
+ Retrying is safe for every call: reads change nothing, and an order is retried
332
+ with its idempotency key.
333
+
334
+ ```ts
335
+ const onesim = new OnesimClient({ timeout: 30_000, maxRetries: 3 });
336
+ ```
337
+
338
+ Every method takes an `AbortSignal` as `{ signal }`. Aborting stops the call,
339
+ retries and polling included, and rejects with the signal's reason. If you
340
+ abort an order, you need its idempotency key to retry it: pass your own.
341
+
342
+ ```ts
343
+ await onesim.balance.retrieve({ signal: AbortSignal.timeout(5_000) });
344
+ ```
345
+
346
+ ## Runtimes
347
+
348
+ Node.js 20 or later, Deno, Bun and Cloudflare Workers, from ES modules
349
+ (`import`) or CommonJS (`require`). The SDK uses the runtime's `fetch`,
350
+ `AbortController` and Web Crypto. To use another `fetch`
351
+ (a proxy, a test double), pass it as `fetch`. Where there is no
352
+ `process.env` (Workers, say), pass `apiKey`.
353
+
354
+ Load it one way in an app. The `import` and `require` copies have their own
355
+ classes, so an error from one is not an `instanceof` the other's.
356
+
357
+ ## Types
358
+
359
+ Every request and response has a type, exported by name: `Catalogue`,
360
+ `Package`, `Order`, `OrderRequest`, `Esim`, `Balance`, `ErrorCode`,
361
+ `WebhookEvent` and the rest. The generated `paths`, `operations`, `components`
362
+ and `webhooks` cover anything else.
363
+
364
+ ## Licence
365
+
366
+ MIT. See [LICENSE](./LICENSE).
@@ -0,0 +1,130 @@
1
+ import { type FetchLike, Http } from './http.js';
2
+ import type { Balance, Catalogue, Esim, EsimList, EsimSummary, ListEsimsParams, ListOrdersParams, Order, OrderList, OrderRequest, Package } from './types.js';
3
+ export interface ClientOptions {
4
+ /**
5
+ * Your API key, `osk_live_…`. A secret for your servers only. Default: the
6
+ * `ONESIM_API_KEY` environment variable.
7
+ */
8
+ apiKey?: string;
9
+ /** Default `https://api.onesim.global`. */
10
+ baseURL?: string;
11
+ /**
12
+ * How long one attempt may take, in milliseconds. Default 60 000: placing an
13
+ * order can make two calls to the network provider of up to 20 seconds each.
14
+ */
15
+ timeout?: number;
16
+ /** How many times a failed request is retried. Default 2. */
17
+ maxRetries?: number;
18
+ /** A `fetch` to use instead of the global one (e.g. in tests). */
19
+ fetch?: FetchLike;
20
+ }
21
+ export interface RequestOptions {
22
+ /** Aborting it stops the call, retries included, and rejects with its reason. */
23
+ signal?: AbortSignal;
24
+ }
25
+ export interface CreateOrderOptions extends RequestOptions {
26
+ /**
27
+ * A UUID, new for each purchase and the same on every retry of it. Store it
28
+ * with your booking before you call, so a retry after a crash never buys
29
+ * twice. Default: a new UUID for this call, used on all its retries.
30
+ */
31
+ idempotencyKey?: string;
32
+ }
33
+ export interface PollOptions extends RequestOptions {
34
+ /**
35
+ * How long to poll before giving up, in milliseconds, reads and their
36
+ * retries included. Default 660 000 (11 minutes).
37
+ */
38
+ timeout?: number;
39
+ /** How long to wait between reads, in milliseconds. Default 3 000. */
40
+ pollInterval?: number;
41
+ }
42
+ export type CreateAndPollOptions = CreateOrderOptions & PollOptions;
43
+ /**
44
+ * The onesim partner API.
45
+ *
46
+ * ```ts
47
+ * import OnesimClient from '@onesim.global/sdk';
48
+ *
49
+ * const onesim = new OnesimClient(); // reads ONESIM_API_KEY
50
+ * const catalogue = await onesim.packages.list();
51
+ * ```
52
+ */
53
+ export declare class OnesimClient {
54
+ /** Your catalogue: what you can buy and what it costs you. */
55
+ readonly packages: Packages;
56
+ /** Buying blank eSIMs, packages and bundles. */
57
+ readonly orders: Orders;
58
+ /** The eSIMs you own, with their packages and usage. */
59
+ readonly esims: Esims;
60
+ /** Your partner balance. */
61
+ readonly balance: BalanceResource;
62
+ constructor(options?: ClientOptions);
63
+ }
64
+ export declare class Packages {
65
+ #private;
66
+ constructor(http: Http);
67
+ /** `GET /v1/packages`: your packages and the price of a blank eSIM. A `null` price means "not offered that way". */
68
+ list(options?: RequestOptions): Promise<Catalogue>;
69
+ /** `GET /v1/packages/{id}`. */
70
+ retrieve(packageId: string, options?: RequestOptions): Promise<Package>;
71
+ }
72
+ export declare class Orders {
73
+ #private;
74
+ constructor(http: Http);
75
+ /**
76
+ * `POST /v1/orders`: buy a blank eSIM (`type: 'esim'`), a package on an eSIM
77
+ * you own (`type: 'package'`) or a new eSIM with a package (`type: 'bundle'`).
78
+ * Resolves with the order as the API answers it: `completed`, or `pending`
79
+ * (follow it with `orders.poll`, or use `orders.createAndPoll`).
80
+ *
81
+ * Every attempt of this call sends the same Idempotency-Key, so a retry
82
+ * never buys twice. Pass your own `idempotencyKey`, stored with your
83
+ * booking, to make retries across restarts safe too. Any `OnesimError`
84
+ * thrown carries the key it used as `error.idempotencyKey`.
85
+ */
86
+ create(body: OrderRequest, options?: CreateOrderOptions): Promise<Order>;
87
+ /**
88
+ * `orders.create`, then `orders.poll` while the order is pending. Resolves
89
+ * with the final order whatever its status (`completed`, `failed` or
90
+ * `refunded`): a `502 provisioning_failed` is not thrown but resolves with
91
+ * its failed order, so check `order.status`. Other errors are thrown, with
92
+ * the Idempotency-Key as `error.idempotencyKey`; `PollTimeoutError` when
93
+ * `timeout` runs out first.
94
+ */
95
+ createAndPoll(body: OrderRequest, options?: CreateAndPollOptions): Promise<Order>;
96
+ /** `GET /v1/orders/{id}`. Reading a pending order also moves it forward. */
97
+ retrieve(orderId: string, options?: RequestOptions): Promise<Order>;
98
+ /** `GET /v1/orders`: one page of your orders, newest first. */
99
+ list(params?: ListOrdersParams, options?: RequestOptions): Promise<OrderList>;
100
+ /** Every order matching `params`, newest first, following `next_cursor` page after page. */
101
+ listAll(params?: ListOrdersParams, options?: RequestOptions): AsyncGenerator<Order, void, undefined>;
102
+ /**
103
+ * Reads the order until it is no longer `pending`, and resolves with it:
104
+ * `completed`, `failed` or `refunded`. A pending order completes or fails
105
+ * within about ten minutes. `timeout` bounds the whole poll, reads and
106
+ * their retries included: when it runs out, throws `PollTimeoutError` with
107
+ * the order as last read.
108
+ */
109
+ poll(orderId: string, options?: PollOptions): Promise<Order>;
110
+ }
111
+ export declare class Esims {
112
+ #private;
113
+ constructor(http: Http);
114
+ /**
115
+ * `GET /v1/esims/{id}`: the eSIM with its packages and usage, read live from
116
+ * the network. When the network does not answer, the last known values with
117
+ * `refreshed_at: null`.
118
+ */
119
+ retrieve(esimId: string, options?: RequestOptions): Promise<Esim>;
120
+ /** `GET /v1/esims`: one page of your eSIMs, newest first. */
121
+ list(params?: ListEsimsParams, options?: RequestOptions): Promise<EsimList>;
122
+ /** Every eSIM matching `params`, newest first, following `next_cursor` page after page. */
123
+ listAll(params?: ListEsimsParams, options?: RequestOptions): AsyncGenerator<EsimSummary, void, undefined>;
124
+ }
125
+ export declare class BalanceResource {
126
+ #private;
127
+ constructor(http: Http);
128
+ /** `GET /v1/balance`: your balance, overdraft and what you can spend now, in cents. */
129
+ retrieve(options?: RequestOptions): Promise<Balance>;
130
+ }