airalo-sdk-type
Version:
UNOFFICIAL AIRALO API INTEGRATION FOR JAVASCRIPT/TYPESCRIPT
353 lines (272 loc) • 9.88 kB
Markdown
# airalo-sdk-type
> Unofficial TypeScript/JavaScript SDK for the [Airalo Partner API](https://partners-api.airalo.com)
[](https://www.npmjs.com/package/airalo-sdk-type)
[](https://opensource.org/licenses/ISC)
[](https://www.typescriptlang.org/)
---
## Table of contents
- [Installation](#installation)
- [Quick start](#quick-start)
- [Environments](#environments)
- [API reference](#api-reference)
- [Auth](#auth)
- [Packages](#packages)
- [Orders](#orders)
- [eSIMs](#esims)
- [Balance](#balance)
- [Notifications](#notifications)
- [Misc](#misc)
- [Response format](#response-format)
- [All methods](#all-methods)
- [Contributing](#contributing)
- [License](#license)
---
## Installation
```bash
npm install airalo-sdk-type
# or
yarn add airalo-sdk-type
```
---
## Quick start
```typescript
import Airalo from "airalo-sdk-type";
// 1. Point to sandbox or production
Airalo.setHost("https://sandbox-partners-api.airalo.com");
// 2. Authenticate — token is stored automatically
await Airalo.auth.TOKEN({
client_id: "YOUR_CLIENT_ID",
client_secret: "YOUR_CLIENT_SECRET"
});
// 3. Fetch available packages
const { data } = await Airalo.Package.Packages();
console.log(data);
// 4. Place an order
const order = await Airalo.Order.SubmitOrder({
quantity: "1",
package_id: "chinacom-7days-1gb"
});
console.log(order.data?.sims[0].qrcode);
```
---
## Environments
| Environment | Base URL |
| ----------- | ----------------------------------------- |
| Sandbox | `https://sandbox-partners-api.airalo.com` |
| Production | `https://partners-api.airalo.com` |
```typescript
// Sandbox (default)
Airalo.setHost("https://sandbox-partners-api.airalo.com");
// Production
Airalo.setHost("https://partners-api.airalo.com");
// Enable request/response logging
Airalo.setLogger(true);
```
---
## API reference
### Auth
```typescript
// Fetch and store an access token
await Airalo.auth.TOKEN({
client_id: "YOUR_CLIENT_ID",
client_secret: "YOUR_CLIENT_SECRET"
});
```
---
### Packages
```typescript
// List all available packages
const all = await Airalo.Package.Packages();
// Filter by country, page, and limit
const jp = await Airalo.Package.Packages({
"filter[country]": "JP",
limit: 10,
page: 1
});
```
---
### Orders
```typescript
// Place a synchronous order — response includes SIM + QR code immediately
const order = await Airalo.Order.SubmitOrder({
quantity: "1",
package_id: "chinacom-7days-1gb",
type: "sim", // optional, defaults to "sim"
description: "My order", // optional
brand_settings_name: "MyBrand" // optional, null = unbranded
});
// Place an asynchronous order — result is delivered via webhook
await Airalo.Order.SubmitOrderAsync({
quantity: "1",
package_id: "chinacom-7days-1gb",
webhook_url: "https://myapp.com/webhook",
to_email: "user@example.com", // optional
sharing_option: ["link", "pdf"], // optional, required if to_email is set
copy_address: ["cc@example.com"] // optional
});
// Place a top-up order for an existing eSIM
await Airalo.Order.SubmitTopUpOrder({
package_id: "bonbon-mobile-30days-3gb-topup",
iccid: "8934000000000087299",
description: "Top-up" // optional
});
// List orders with filters
const orders = await Airalo.Order.GetOrderList({
"filter[order_status]": "completed", // completed | failed | refunded
"filter[iccid]": "89343",
"filter[code]": "20221021-003188",
"filter[created_at]": "2024-01-01 - 2024-12-31",
include: "sims,status",
limit: 20,
page: 1
});
// Get a single order by ID
const single = await Airalo.Order.GetOrder(731579);
// List all order statuses
const statuses = await Airalo.Order.GetOrderStatuses();
// Get a specific status by slug
const status = await Airalo.Order.GetOrderStatusBySlug("completed");
```
---
### eSIMs
```typescript
// List eSIMs with optional filters
const sims = await Airalo.Sims.GetSimList({
"filter[iccid]": "8910300000",
"filter[created_at]": "2024-01-01 - 2024-12-31",
include: "order,order.status,share",
limit: 10,
page: 1
});
// Get a single eSIM by ICCID
const sim = await Airalo.Sims.GetSim("8910300000033289733");
// Get installation instructions (QR + manual)
const instructions = await Airalo.Sims.GetSimInstructions(
"8910300000033289733"
);
// Get current data usage
const usage = await Airalo.Sims.GetDataUsage("8910300000033289733");
// usage.data.remaining — bytes remaining
// usage.data.total — total bytes
// usage.data.status — NOT_ACTIVE | ACTIVE | FINISHED | EXPIRED
// List available top-up packages for an eSIM
const topups = await Airalo.Sims.GetTopUpPackageList("8910300000033289733");
// Get package history for an eSIM
const history = await Airalo.Sims.GetSimPackageHistory("8910300000033289733");
// Update the brand name shown on an eSIM
await Airalo.Sims.UpdateSimBrand("8910300000033289733", "MyBrand");
```
---
### Balance
```typescript
const balance = await Airalo.Balance.GetBalance();
console.log(balance.data?.balances.availableBalance.amount);
console.log(balance.data?.balances.availableBalance.currency);
```
---
### Notifications
```typescript
// Opt in to low-data webhook notifications
await Airalo.Notification.NotificationOptIn({
type: "webhook_low_data",
webhook_url: "https://myapp.com/webhook"
});
// Opt in to credit-limit notifications with threshold levels (%)
await Airalo.Notification.NotificationOptIn({
type: "webhook_credit_limit",
webhook_url: "https://myapp.com/webhook",
levels: [50, 70, 80, 90]
});
// Opt out
await Airalo.Notification.NotificationOptOut({
type: "webhook_low_data" // email_low_data | email_credit_limit | webhook_low_data | webhook_credit_limit
});
// Get current notification settings
const settings = await Airalo.Notification.GetNotification();
// Simulate a webhook event (sandbox only)
await Airalo.Notification.SimulateWebhook({
event: "low_data_notification",
type: "expire_1",
iccid: "8997212330099025334"
});
```
---
### Misc
```typescript
// List eSIM-compatible devices
const devices = await Airalo.Misc.GetCompatibleDevices();
// Create an eSIM voucher
const voucher = await Airalo.Misc.CreateEsimVoucher({
package_id: "chinacom-7days-1gb",
quantity: 1
});
```
---
## Response format
Every method returns an `ApiResult<T>` object:
```typescript
// Success
{
success: true,
data: T,
message: "Амжилттай."
}
// Error
{
success: false,
data: null,
message: "Error message from API"
}
```
Check `result.success` before accessing `result.data`:
```typescript
const result = await Airalo.Order.SubmitOrder({
quantity: "1",
package_id: "chinacom-7days-1gb"
});
if (result.success) {
console.log(result.data.sims[0].qrcode_url);
} else {
console.error(result.message);
}
```
---
## All methods
| Module | Method | Description |
| -------------- | ---------------------- | --------------------------------------- |
| `auth` | `TOKEN` | Fetch and store access token |
| `Package` | `Packages` | List packages (filterable by country) |
| `Order` | `SubmitOrder` | Place a synchronous order |
| `Order` | `SubmitOrderAsync` | Place an asynchronous order via webhook |
| `Order` | `SubmitTopUpOrder` | Top up an existing eSIM |
| `Order` | `GetOrderList` | List orders with filters |
| `Order` | `GetOrder` | Get a single order by ID |
| `Order` | `GetOrderStatuses` | List all order statuses |
| `Order` | `GetOrderStatusBySlug` | Get a single status by slug |
| `Sims` | `GetSimList` | List eSIMs with filters |
| `Sims` | `GetSim` | Get a single eSIM by ICCID |
| `Sims` | `GetSimInstructions` | Get installation instructions |
| `Sims` | `GetDataUsage` | Get current data usage |
| `Sims` | `GetTopUpPackageList` | List available top-up packages |
| `Sims` | `GetSimPackageHistory` | Get package history |
| `Sims` | `UpdateSimBrand` | Update eSIM brand name |
| `Balance` | `GetBalance` | Get account balance |
| `Notification` | `NotificationOptIn` | Enable a notification type |
| `Notification` | `NotificationOptOut` | Disable a notification type |
| `Notification` | `GetNotification` | Get current notification settings |
| `Notification` | `SimulateWebhook` | Simulate a webhook event (sandbox) |
| `Misc` | `GetCompatibleDevices` | List eSIM-compatible devices |
| `Misc` | `CreateEsimVoucher` | Create an eSIM voucher |
---
## Contributing
Pull requests are welcome. For major changes, please open an issue first.
```bash
git clone https://github.com/togtokh-dev/airalo.git
cd airalo
npm install
npm test
```
---
## License
[ISC](https://opensource.org/licenses/ISC) © Buyantogtokh
> This is an **unofficial** SDK and is not affiliated with or endorsed by Airalo.