@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 +47 -0
- package/LICENSE +21 -0
- package/README.md +376 -2
- package/dist/cjs/client.d.ts +130 -0
- package/dist/cjs/client.js +314 -0
- package/dist/cjs/errors.d.ts +126 -0
- package/dist/cjs/errors.js +199 -0
- package/dist/cjs/generated/openapi.d.ts +2090 -0
- package/dist/cjs/generated/openapi.js +5 -0
- package/dist/cjs/http.d.ts +40 -0
- package/dist/cjs/http.js +211 -0
- package/dist/cjs/index.d.ts +8 -0
- package/dist/cjs/index.js +27 -0
- package/dist/cjs/package.json +3 -0
- package/dist/cjs/types.d.ts +56 -0
- package/dist/cjs/types.js +4 -0
- package/dist/cjs/webhooks.d.ts +26 -0
- package/dist/cjs/webhooks.js +98 -0
- package/dist/esm/client.d.ts +130 -0
- package/dist/esm/client.js +306 -0
- package/dist/esm/errors.d.ts +126 -0
- package/dist/esm/errors.js +182 -0
- package/dist/esm/generated/openapi.d.ts +2090 -0
- package/dist/esm/generated/openapi.js +4 -0
- package/dist/esm/http.d.ts +40 -0
- package/dist/esm/http.js +205 -0
- package/dist/esm/index.d.ts +8 -0
- package/dist/esm/index.js +5 -0
- package/dist/esm/types.d.ts +56 -0
- package/dist/esm/types.js +3 -0
- package/dist/esm/webhooks.d.ts +26 -0
- package/dist/esm/webhooks.js +95 -0
- package/package.json +76 -4
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
|
-
#
|
|
1
|
+
# onesim eSIM API SDK for TypeScript
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
}
|