@onesim.global/sdk 0.0.0-stage → 0.1.1

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,47 @@
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.1
8
+
9
+ - The npm page says what the package is for: a description and keywords that
10
+ name the onesim eSIM API, and a README that opens with what you can build
11
+ and links to the reference, API access, the agent skill and `llms.txt`. No
12
+ code changes.
13
+
14
+ ## 0.1.0
15
+
16
+ The first release, for version 1 of the onesim partner API.
17
+
18
+ - `new OnesimClient()`, also the default export, with the key from
19
+ `ONESIM_API_KEY` or `apiKey`, and `baseURL`, `timeout` (per attempt),
20
+ `maxRetries` and `fetch`: your catalogue (`packages.list`,
21
+ `packages.retrieve`), orders (`orders.create`, `orders.createAndPoll`,
22
+ `orders.retrieve`, `orders.list`, `orders.listAll`, `orders.poll`), eSIMs
23
+ (`esims.retrieve`, `esims.list`, `esims.listAll`) and your balance
24
+ (`balance.retrieve`).
25
+ - `orders.create` sends one Idempotency-Key on every attempt, yours or a new
26
+ UUID, and puts it on any error it throws, so a purchase is never bought
27
+ twice.
28
+ - `orders.poll` follows a pending order (`202`) until it is completed or
29
+ failed; `orders.createAndPoll` creates the order and polls it, and resolves
30
+ with the final order, a failed one included.
31
+ - Retries with backoff when there is no answer and on `429` (after
32
+ `Retry-After`) and `5xx`; never on `provisioning_failed`,
33
+ `esims_unavailable` or another `4xx`. A timeout per attempt, and an
34
+ `AbortSignal` on every call.
35
+ - Errors as classes, all extending `OnesimError`: `APIError` with the API's
36
+ `code`, `requestId` and details, and its subclasses by status
37
+ (`BadRequestError`, `AuthenticationError`, `PermissionDeniedError`,
38
+ `NotFoundError`, `ConflictError`, `RateLimitError`,
39
+ `InternalServerError`); `APIConnectionError` and
40
+ `APIConnectionTimeoutError`; `PollTimeoutError`;
41
+ `WebhookVerificationError`.
42
+ - `verifyWebhook` checks the `Onesim-Signature` header and returns the event,
43
+ typed by its `type`.
44
+ - Types for every request, response and event, generated from the API's
45
+ contract, with its field names.
46
+ - No dependencies. ES modules and CommonJS. Node.js 20 or later, Deno, Bun and
47
+ 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,377 @@
1
- # Temporary Holding Version
1
+ # onesim eSIM API SDK 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 eSIM API, the partner API businesses use
4
+ to sell travel eSIMs under their own brand, inside their own product such as a
5
+ travel app or a booking flow. Your servers use it to buy blank eSIMs, data
6
+ packages, top-ups and bundles from your partner balance, to read your
7
+ catalogue, orders and eSIMs with their data usage, and to verify webhooks.
8
+
9
+ Its types come from the API's contract. Field names are the API's own
10
+ (`esim_price`, `next_cursor`, `activation_code`): what the reference at
11
+ <https://api.onesim.global/docs> shows is what you get. Read the guide there
12
+ first; this page covers the SDK.
13
+
14
+ ## Links
15
+
16
+ - [API reference and guide](https://api.onesim.global/docs/)
17
+ - [Getting API access](https://onesim.global/partners/technology): the API is
18
+ for onesim partners, who create their keys in the partner platform.
19
+ - [Agent skill](https://onesim.global/.well-known/agent-skills/onesim-partner-api/SKILL.md)
20
+ for coding agents that write the integration.
21
+ - [llms.txt](https://api.onesim.global/llms.txt): the API for AI assistants.
22
+
23
+ ## Install
24
+
25
+ ```sh
26
+ npm install @onesim.global/sdk
27
+ # or
28
+ pnpm add @onesim.global/sdk
29
+ # or
30
+ yarn add @onesim.global/sdk
31
+ ```
32
+
33
+ It has no dependencies and runs on Node.js 20 or later, Deno, Bun and
34
+ Cloudflare Workers. It ships as an ES module and as CommonJS:
35
+
36
+ ```js
37
+ const { OnesimClient } = require('@onesim.global/sdk');
38
+ ```
39
+
40
+ ## Quick start
41
+
42
+ ```ts
43
+ import OnesimClient from '@onesim.global/sdk';
44
+
45
+ const onesim = new OnesimClient(); // reads ONESIM_API_KEY
46
+
47
+ const catalogue = await onesim.packages.list(); // your packages and prices
48
+ const balance = await onesim.balance.retrieve(); // balance.available: cents to spend
49
+ ```
50
+
51
+ The client reads your key from the `ONESIM_API_KEY` environment variable, or
52
+ takes it as `new OnesimClient({ apiKey })`. `OnesimClient` is also a named
53
+ export.
54
+
55
+ Your key is a secret for your servers only. Never put it in an app, a browser
56
+ or a URL. Every key is live: what it buys is real and paid from your balance.
57
+
58
+ ## Buying
59
+
60
+ | `type` | You get | You pay |
61
+ | --------- | ---------------------------------------------------- | ----------------------- |
62
+ | `esim` | A blank eSIM with its activation code, no data. | `catalogue.esim_price` |
63
+ | `package` | A package on an eSIM you own: the first or a top-up. | the package's `price` |
64
+ | `bundle` | A new eSIM with the package already on it. | `package.bundle.amount` |
65
+
66
+ A `null` price means "not offered that way". Amounts are in cents of your
67
+ account's currency. Pass `expected_amount`, the price you showed your customer:
68
+ if the price has changed since, the order is refused with `price_changed` and
69
+ nothing is charged.
70
+
71
+ ```ts
72
+ const order = await onesim.orders.createAndPoll(
73
+ {
74
+ type: 'bundle',
75
+ package_id: pkg.id,
76
+ reference: booking.id,
77
+ expected_amount: pkg.bundle!.amount
78
+ },
79
+ { idempotencyKey: booking.orderKey }
80
+ );
81
+
82
+ if (order.status === 'completed') {
83
+ // order.esim.activation_code for the QR code, order.esim.ios_install_url,
84
+ // order.esim.android_install_url
85
+ } else {
86
+ // failed: the amount is already back on your balance
87
+ }
88
+ ```
89
+
90
+ ### Idempotency keys
91
+
92
+ Every purchase needs its own key, a UUID. The SDK sends the same key on every
93
+ retry it makes, so one call never buys twice.
94
+
95
+ Make the key yourself, store it with your booking before you call, and pass it
96
+ as `idempotencyKey`. If your process crashes or the call throws, call `create`
97
+ (or `createAndPoll`) again with the same key and body: you get the same order,
98
+ charged once.
99
+
100
+ ```ts
101
+ booking.orderKey ??= crypto.randomUUID();
102
+ await saveBooking(booking);
103
+ const order = await onesim.orders.create(body, {
104
+ idempotencyKey: booking.orderKey
105
+ });
106
+ ```
107
+
108
+ Without a key, the SDK makes a new one for each call. An error thrown by
109
+ `create` or `createAndPoll` carries the key it used as `error.idempotencyKey`.
110
+
111
+ The same key with a different body is refused with `idempotency_conflict`. A
112
+ `502 provisioning_failed` is final: that order failed and was refunded, and
113
+ buying again needs a new key.
114
+
115
+ ### Polling
116
+
117
+ `create` answers at once when the order is complete. When the network provider
118
+ has not confirmed yet, the order comes back with `status: 'pending'`. It
119
+ completes or fails within about ten minutes.
120
+
121
+ `orders.create` never waits: it returns the order as the API answers it,
122
+ pending or not. Follow a pending order with `orders.poll`, or with the
123
+ `order.completed` and `order.failed` webhooks:
124
+
125
+ ```ts
126
+ const final = await onesim.orders.poll(order.id); // every 3 s, for up to 11 minutes
127
+ ```
128
+
129
+ `orders.poll` resolves with the order once it is `completed`, `failed` or
130
+ `refunded`. Its `timeout` (milliseconds, default 660 000) bounds the whole
131
+ poll, slow reads and their retries included; `pollInterval` (default 3 000) is
132
+ the pause between reads. If time runs out first, it throws `PollTimeoutError`,
133
+ whose `order` is the order as last read (absent only if no read answered in
134
+ time).
135
+
136
+ `orders.createAndPoll` does both: it creates the order, polls it while it is
137
+ pending, and resolves with the final order, whatever its status. A failed
138
+ order does not throw here: `502 provisioning_failed` resolves with the failed
139
+ order. So check `order.status`. Other errors still throw. It takes
140
+ `idempotencyKey`, `timeout` and `pollInterval`.
141
+
142
+ ## Errors
143
+
144
+ Every error the SDK throws for the API extends `OnesimError`.
145
+
146
+ An answer with an error status is an `APIError`, or a subclass named after its
147
+ status:
148
+
149
+ | Status | Class | Codes |
150
+ | ------ | ----------------------- | ------------------------------------------------------------------------------------------- |
151
+ | 400 | `BadRequestError` | `invalid_request`, `idempotency_key_required` |
152
+ | 401 | `AuthenticationError` | `unauthorized` |
153
+ | 403 | `PermissionDeniedError` | `not_offered` |
154
+ | 404 | `NotFoundError` | `not_found` |
155
+ | 409 | `ConflictError` | `idempotency_conflict`, `esim_busy`, `price_changed`, `esim_limit_reached`, `esim_unusable` |
156
+ | 429 | `RateLimitError` | `rate_limited` |
157
+ | 5xx | `InternalServerError` | `internal_error`, `provisioning_failed`, `esims_unavailable` |
158
+ | other | `APIError` | e.g. 402 `insufficient_balance` |
159
+
160
+ The other errors:
161
+
162
+ | Class | When |
163
+ | --------------------------- | ------------------------------------------------------------------------- |
164
+ | `APIConnectionError` | No answer after every retry: the network failed or the attempt timed out. |
165
+ | `APIConnectionTimeoutError` | An `APIConnectionError` whose last attempt ran out of `timeout`. |
166
+ | `PollTimeoutError` | Polling ran out of time; `error.order` is still pending. |
167
+ | `WebhookVerificationError` | A webhook delivery failed verification. |
168
+
169
+ After an `APIConnectionError` from `create` you cannot know whether the order
170
+ was placed: call `create` again with the same key and body, and you get the
171
+ order, paid for once.
172
+
173
+ Act on `error.code`; `error.message` is for people and may change. Quote
174
+ `error.requestId` when you contact us. New codes may be added: handle a code
175
+ you do not know by `error.status`. `code` is `null` when the answer was not
176
+ the API's (an HTML page from a proxy, say).
177
+
178
+ ```ts
179
+ import { APIError, ConflictError } from '@onesim.global/sdk';
180
+
181
+ try {
182
+ await onesim.orders.create(body, { idempotencyKey });
183
+ } catch (error) {
184
+ if (error instanceof ConflictError && error.code === 'price_changed') {
185
+ // error.amount is the current amount
186
+ } else if (error instanceof APIError) {
187
+ switch (error.code) {
188
+ case 'insufficient_balance':
189
+ // top up your balance
190
+ break;
191
+ case 'esim_limit_reached':
192
+ // error.limit is 'blank' or 'daily'
193
+ break;
194
+ default:
195
+ console.error(error.status, error.code, error.requestId);
196
+ }
197
+ } else {
198
+ throw error;
199
+ }
200
+ }
201
+ ```
202
+
203
+ The codes and their meaning are in the guide, under "Errors".
204
+
205
+ ## Paging
206
+
207
+ `orders.list` and `esims.list` return one page as the API sends it:
208
+ `{ data, next_cursor }`, newest first. Pass `next_cursor` as `cursor` for the
209
+ next page; it is `null` on the last one.
210
+
211
+ `orders.listAll` and `esims.listAll` follow the pages for you:
212
+
213
+ ```ts
214
+ for await (const order of onesim.orders.listAll({
215
+ created_after: new Date('2026-11-01')
216
+ })) {
217
+ console.log(order.id, order.status);
218
+ }
219
+ ```
220
+
221
+ `created_after` takes a `Date` or an ISO string. The orders filters are
222
+ `esim_id`, `reference` and `created_after`; the eSIMs filter is `iccid`.
223
+
224
+ ## Webhooks
225
+
226
+ `verifyWebhook` checks the `Onesim-Signature` header against your endpoint's
227
+ signing secret (`whsec_…`) and the delivery's age, then returns the event. It
228
+ needs no API key.
229
+
230
+ It needs the raw body, exactly as received. Parsed and re-serialised JSON has
231
+ other bytes, and its signature does not match.
232
+
233
+ With Express:
234
+
235
+ ```ts
236
+ import express from 'express';
237
+ import { WebhookVerificationError, verifyWebhook } from '@onesim.global/sdk';
238
+
239
+ const app = express();
240
+
241
+ app.post(
242
+ '/onesim/webhooks',
243
+ express.raw({ type: 'application/json' }),
244
+ async (req, res) => {
245
+ let event;
246
+ try {
247
+ event = await verifyWebhook({
248
+ payload: req.body, // a Buffer, thanks to express.raw
249
+ signature: req.get('onesim-signature'),
250
+ secret: process.env.ONESIM_WEBHOOK_SECRET!
251
+ });
252
+ } catch (error) {
253
+ if (error instanceof WebhookVerificationError)
254
+ return res.status(400).send(error.reason);
255
+ throw error;
256
+ }
257
+ await handle(event);
258
+ res.sendStatus(204);
259
+ }
260
+ );
261
+ ```
262
+
263
+ With a fetch-style handler (Cloudflare Workers, Deno, Bun, Next.js route
264
+ handlers):
265
+
266
+ ```ts
267
+ export async function POST(request: Request): Promise<Response> {
268
+ let event;
269
+ try {
270
+ event = await verifyWebhook({
271
+ payload: await request.text(),
272
+ signature: request.headers.get('onesim-signature'),
273
+ secret: process.env.ONESIM_WEBHOOK_SECRET!
274
+ });
275
+ } catch (error) {
276
+ if (error instanceof WebhookVerificationError)
277
+ return new Response(error.reason, { status: 400 });
278
+ throw error;
279
+ }
280
+ await handle(event);
281
+ return new Response(null, { status: 204 });
282
+ }
283
+ ```
284
+
285
+ The event is typed by its `type`:
286
+
287
+ ```ts
288
+ import type { WebhookEvent } from '@onesim.global/sdk';
289
+
290
+ async function handle(event: WebhookEvent) {
291
+ switch (event.type) {
292
+ case 'order.completed':
293
+ case 'order.failed':
294
+ // event.data.id, event.data.status, event.data.reference
295
+ break;
296
+ case 'package.usage':
297
+ // event.data.percent_used
298
+ break;
299
+ default:
300
+ // We add event types without notice: ignore one you do not know.
301
+ }
302
+ }
303
+ ```
304
+
305
+ Answer with any `2xx` within 10 seconds. Anything else is retried, seven times
306
+ over about two days.
307
+ Delivery is at least once and in no particular order: ignore an event `id` you
308
+ have seen, and read the order or eSIM when order matters.
309
+
310
+ A delivery more than five minutes old or ahead is refused
311
+ (`timestamp_out_of_tolerance`); `toleranceSeconds` changes that. A header may
312
+ carry more than one `v1` signature; any match is accepted.
313
+
314
+ ## Configuration
315
+
316
+ ```ts
317
+ const onesim = new OnesimClient({
318
+ apiKey: 'osk_live_…', // default: process.env.ONESIM_API_KEY
319
+ baseURL: 'https://api.onesim.global', // the default
320
+ timeout: 60_000, // per attempt, in milliseconds
321
+ maxRetries: 2,
322
+ fetch // another fetch, e.g. a test double
323
+ });
324
+ ```
325
+
326
+ The options' types are exported: `ClientOptions`, `RequestOptions`,
327
+ `CreateOrderOptions` and `PollOptions`.
328
+
329
+ ## Retries and timeouts
330
+
331
+ Each attempt may take `timeout` milliseconds (default 60 000: placing an order
332
+ can make two calls of up to 20 seconds each to the network provider). A failed
333
+ attempt is retried up to `maxRetries` times (default 2), after a pause that
334
+ grows from about half a second to at most 8 seconds, with jitter.
335
+
336
+ | Retried | Not retried |
337
+ | --------------------------------------------- | ---------------------------------- |
338
+ | No answer: a network error or a timeout | Any other `4xx` |
339
+ | `429`, after its `Retry-After` (at most 60 s) | `502 provisioning_failed`: final |
340
+ | `500`, `502`, `503`, `504` | `503 esims_unavailable`: try later |
341
+
342
+ Retrying is safe for every call: reads change nothing, and an order is retried
343
+ with its idempotency key.
344
+
345
+ ```ts
346
+ const onesim = new OnesimClient({ timeout: 30_000, maxRetries: 3 });
347
+ ```
348
+
349
+ Every method takes an `AbortSignal` as `{ signal }`. Aborting stops the call,
350
+ retries and polling included, and rejects with the signal's reason. If you
351
+ abort an order, you need its idempotency key to retry it: pass your own.
352
+
353
+ ```ts
354
+ await onesim.balance.retrieve({ signal: AbortSignal.timeout(5_000) });
355
+ ```
356
+
357
+ ## Runtimes
358
+
359
+ Node.js 20 or later, Deno, Bun and Cloudflare Workers, from ES modules
360
+ (`import`) or CommonJS (`require`). The SDK uses the runtime's `fetch`,
361
+ `AbortController` and Web Crypto. To use another `fetch`
362
+ (a proxy, a test double), pass it as `fetch`. Where there is no
363
+ `process.env` (Workers, say), pass `apiKey`.
364
+
365
+ Load it one way in an app. The `import` and `require` copies have their own
366
+ classes, so an error from one is not an `instanceof` the other's.
367
+
368
+ ## Types
369
+
370
+ Every request and response has a type, exported by name: `Catalogue`,
371
+ `Package`, `Order`, `OrderRequest`, `Esim`, `Balance`, `ErrorCode`,
372
+ `WebhookEvent` and the rest. The generated `paths`, `operations`, `components`
373
+ and `webhooks` cover anything else.
374
+
375
+ ## Licence
376
+
377
+ 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
+ }